← Back to the blog

How to Add an MCP Server to Cursor (With Hilbana as the Example)

How to configure MCP servers in Cursor with mcp.json: remote and local servers, environment variables, OAuth, and a real example connecting Hilbana with an API key.

Equipo HilbanaProducto

Cursor · MCP · Tutorial

How to Add an MCP Server to Cursor (With Hilbana as the Example)

In Cursor, an MCP server is a few lines in a JSON file. The part that trips people up is not the format but the details around it: where the file goes, how to keep a key out of it, and what happens when the server uses OAuth. This guide covers those, then connects Hilbana as a worked example.

What follows about Cursor comes from its MCP documentation, read on 2 November 2026. Cursor’s menus change often, so where the docs and your screen disagree, trust the screen.

Where the configuration lives

Cursor reads MCP servers from a file called mcp.json, in two possible places:

The documentation does not say which one wins if both define the same server, so avoid defining one server in both.

The two formats

A remote server needs a URL and, if it asks for one, headers:

{
  "mcpServers": {
    "server-name": {
      "url": "https://example.com/mcp",
      "headers": { "API_KEY": "value" }
    }
  }
}

A local server runs a command on your machine:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": { "API_KEY": "value" }
    }
  }
}

Keep secrets out of the file

Cursor resolves variables inside command, args, env, url and headers. The one you will use most is ${env:NAME}, which reads an environment variable. Others include ${userHome} and ${workspaceFolder}.

So instead of pasting a key, write "Bearer ${env:MY_KEY}" and define MY_KEY before opening Cursor. This matters most for .cursor/mcp.json: it sits inside your repository.

Authentication

When a token expires, Cursor refreshes it if the server issued a refresh token; otherwise you sign in again.

Turn it on and check it

Cursor’s documentation says you manage MCP servers from Customize in the sidebar, where you can also toggle each one on or off. Older versions and many guides call this place Settings → Tools & MCP, so look for whichever your version shows. The server should appear as enabled with its list of tools. If it does not, restart Cursor.

A real example: connecting Hilbana

Hilbana is a task board for teams whose AI agents take tasks, finish them and keep what they learned. Cursor connects to it through its MCP server with an API key.

1. Create the key. In Hilbana, open Settings → Agents → API keys (admins only) and create one. You can make it read-only or limit it to one project. It starts with hil_ and is shown only once.

2. Add the server to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "hilbana": {
      "url": "https://app.hilbana.com/mcp",
      "headers": { "Authorization": "Bearer ${env:HILBANA_API_KEY}" }
    }
  }
}

3. Define the variable HILBANA_API_KEY with your key before you open Cursor, and restart it.

4. Try it. Ask the agent in plain language: “List my Hilbana projects.” Then: “Get the next agent-ready issue and start on it.” If it answers with your projects, you are connected.

To revoke access, delete the key in Settings → Agents → API keys: Cursor loses access immediately. The same setup works for Codex, and there is a Claude Code version of this guide.

What to watch out for

You can try Hilbana for free: the Free plan does not expire and asks for no card.


The Cursor behaviours in this article were read from cursor.com/docs/context/mcp on 2 November 2026. The Hilbana steps come from our own documentation.

← Back to the blog