How to add an MCP server to Cursor

TL;DR. Updated August 2026. Two ways in. One click: open an install link such as the Add Hatchable to Cursor button, confirm, and approve the OAuth tab. Manual: open Cursor → Settings → Cursor Settings → Tools & MCP (older builds call the tab MCP) → New MCP server, which opens ~/.cursor/mcp.json; paste the JSON config and save. Cursor picks up the change immediately. Hatchable signs in with OAuth on Cursor 1.0 and later; on older builds, grab a token at hatchable.com and paste it into the Authorization header.

What is an MCP server?

An MCP server (Model Context Protocol) is an external service that Cursor's agent can call: create files, deploy apps, run queries, hit an API. Any service that speaks MCP can be plugged in, and Cursor will let the agent invoke its tools as part of a conversation.

Hatchable's MCP server lets Cursor's agent create Hatchable projects, deploy code, and manage the project's database, all without leaving the editor.

Before you start

• Cursor installed, any recent version. Older Cursor builds used a different MCP UI; if you don't see a Tools & MCP (or MCP) tab in Settings, update Cursor first. Cursor 1.0 or later is needed for OAuth over Streamable HTTP.
• A bearer token, if the server uses token auth. Hatchable uses OAuth on Cursor 1.0 and later, so there is no token to copy: the first connection opens a browser tab on hatchable.com, and approving creates your free account. The token form below is for older Cursor builds and for other servers that issue static tokens.

Add the server

1. Open Cursor's MCP settings

   Settings → Cursor Settings → Tools & MCP (older builds: MCP). You'll see a list of any servers already configured and a New MCP server button, which opens ~/.cursor/mcp.json in the editor.

2. Paste the JSON config

   Cursor uses JSON for MCP server entries. For Hatchable on Cursor 1.0 or later, the entry is just the URL and OAuth does the rest:

   {
     "mcpServers": {
       "hatchable": {
         "url": "https://hatchable.com/mcp"
       }
     }
   }

   On an older build, or for a server that issues a static token, add a headers object:

   {
     "mcpServers": {
       "hatchable": {
         "url": "https://hatchable.com/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_TOKEN"
         }
       }
     }
   }

   Swap YOUR_TOKEN for your actual token. If you're adding multiple servers, repeat the block inside mcpServers with a different key name for each one.

3. Save and confirm

   Cursor will re-read the config on save. Back on the MCP page, your new server should show a green "connected" indicator. If it stays red, jump to Troubleshooting below.

4. Ask the agent to use it

   Open the agent panel (⌘+L on macOS) and give it a task that requires the server. For Hatchable:

   "Create a new Hatchable project called hello-world with a page that says hi, and deploy it."

   The agent will invoke the Hatchable tools. Cursor shows a permission prompt the first time each tool runs; accept to continue.

Where the config file lives

If you'd rather edit the config file directly than go through the UI, it's at:

One-click install links vs. editing mcp.json

Cursor has two front doors for the same config, and it helps to know they end in the same place. Checked against Cursor's documentation as of August 2026; Cursor renames its settings panels fairly often, so treat the menu labels as approximate.

The deeplink (one click)

Servers can publish an install link of the form cursor://anysphere.cursor-deeplink/mcp/install?name=NAME&config=BASE64, where config is the server's JSON entry, base64-encoded. Clicking it opens Cursor with an install prompt showing the name and the decoded config; confirm, and Cursor writes the entry to its config for you (in current builds, the global ~/.cursor/mcp.json). Hatchable's link is the button on the connect Cursor how-to and in the docs; its config is nothing but {"url": "https://hatchable.com/mcp"}, which you can confirm in the prompt before accepting. That is the check worth doing for any deeplink: read the decoded config, because a malicious link could just as easily install a command that runs something on your machine.

Editing the file (global or per project)

~/.cursor/mcp.json applies to every workspace; .cursor/mcp.json at a repo root applies only when that project is open, and is the one to commit for a team. Cursor loads both. Either file uses the mcpServers object shown above. For a remote server, url is all that is needed for Streamable HTTP (Cursor also still speaks the older SSE transport from the same key); a headers object carries static tokens, and values can reference ${env:NAME} so the token lives in your environment rather than in the file. On Cursor 1.0 and later, a url-only entry for an OAuth server triggers the browser sign-in the first time Cursor connects, and Cursor keeps the resulting credentials for you.

Seeing the tools Cursor loaded

Cursor Settings → Tools & MCP lists every server with a status dot; expand a server and you see each tool it advertises, with a per-tool toggle and a toggle for the server as a whole (some newer builds surface the same list under Customize in the sidebar). If Hatchable shows as connected but with no tools, that usually means the OAuth step has not completed yet; Cursor typically shows a sign-in action on the server's row for exactly that. Cursor's agent shows the same tool names in chat when it calls them, so if you want to confirm a particular tool exists, that list is the place to look.

Troubleshooting

Cursor shows the server as "not connected"

In order of frequency:

• Invalid JSON. Cursor silently fails on syntax errors. Paste your config into a JSON linter or run cat ~/.cursor/mcp.json | jq.
• Expired or revoked token (token-based setups). Generate a new one and update the Authorization header. On Cursor 1.0 and later, drop the header and let Hatchable sign you in with OAuth instead; if that session lapses, Cursor typically shows a sign-in action on the server's row in Tools & MCP, which reopens the tab at hatchable.com.
• Proxy or VPN. Cursor uses the system HTTPS stack: if your network inspects TLS, Cursor may refuse the connection. Test by running curl -I https://hatchable.com/mcp from the same machine.

The server connects but the agent doesn't call its tools

Cursor's agent only invokes MCP tools when the conversation explicitly needs them. "Help me with this file" won't trigger Hatchable's deploy tool; "Deploy this to Hatchable" will. Be specific: name the tool ("deploy", "create project", "query the app database") in the prompt and the agent will find it.

I switched Hatchable tokens and the old one still works

That's normal: Cursor caches tool manifests. Restart Cursor (or just reload the agent panel) and the cache clears.