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.
Cursor · MCP · Tutorial

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:
~/.cursor/mcp.json: tools available in every project..cursor/mcp.jsonat the root of a project: tools for that project only.
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
- API key or token: put it in
headers(remote) orenv(local), using the variable syntax above. - OAuth: remote servers can use the authorization code flow with PKCE. If the server supports dynamic client registration, Cursor registers itself and you just sign in. For a server that requires a pre-registered app, you add an
authobject withCLIENT_IDand, optionally,CLIENT_SECRETandscopes. Cursor’s docs list the redirect URLs to register.
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
- Trust the server. Cursor’s security notes say MCP servers can access external services and execute code on your behalf. Verify where a server comes from, review the permissions it asks for, and limit the keys you give it.
- Use the narrowest key. If an agent only needs to read, create a read-only key; if it works on one project, limit the key to that project.
- Do not commit keys. Prefer
${env:…}in any file that lives in a repository.
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.