Connect a Remote MCP Server to Claude Code, Desktop and Cursor

There are two ways into the same MCP server. Claude Code and Cursor can set X-API-Key. Claude.ai, Claude Desktop, and Claude mobile add the server URL and open a sign-in screen. Use the path the client actually supports. A header in a client that cannot send one fails in a way that looks like the server is down.

The snippets below are the configuration the server accepts. They use YOUR_KEY on purpose. Put a real key in only on your machine, and only in the clients that take a header.

The server URL is your API origin plus /mcp. On the public site that origin is the API host already used by the dashboard, not a guessed api. subdomain. Copy it from the MCP page or from the docs so the path is /mcp once.

Claude.ai, Claude Desktop, and Claude mobile

Add a custom connector. The URL is the server URL. Leave the API key out.

Server URL: https://<api-origin>/mcp
Transport: HTTP (streamable)
Auth: OAuth sign-in. Do not paste an API key.

The app should receive HTTP 401 with a WWW-Authenticate header and open a browser window on the Calorie API consent screen. Sign in with the account that has the MCP plan, check the host you are returning to, and approve. Read access covers search, portions, recipes, and barcodes. Photo access is a separate scope, shown on that screen when the client asks for it. Stay-connected is offline_access; without it the access token expires in about an hour and the app has to sign in again.

If the app never opens a browser, the server is not sending the 401 challenge. That challenge is on only when OAuth is enabled and the discovery documents are served from the same origin as the MCP URL. Authenticating a Remote MCP Server is the checklist: form-encoded token endpoint, PKCE S256, and resource equal to the MCP URL.

If the browser opens and then says the account cannot connect, the login is not on the MCP plan. Start the trial from MCP pricing. Approving the screen with a REST-only account does not create a working connector. The server refuses to issue a code in that case.

Deny on the consent screen sends the client access_denied and does not create a code.

Claude Code

Claude Code takes a header in the add command.

claude mcp add --transport http calorie-api https://<api-origin>/mcp \
  --header "X-API-Key: YOUR_KEY"

The transport is HTTP, not stdio. The name calorie-api is the server name in the client. The key belongs to the MCP plan. A key from another plan connects and then fails the first tool call with a plan error, which is more confusing than failing at the door. Create the key in the dashboard. The full value is shown once.

Do not commit the command with a real key. YOUR_KEY in a gist is safe. A key that starts with the product prefix in a gist is not.

Cursor

.cursor/mcp.json at the project root, or the user-level MCP config if you want it in every project:

{
  "mcpServers": {
    "calorie-api": {
      "url": "https://<api-origin>/mcp",
      "headers": {
        "X-API-Key": "YOUR_KEY"
      }
    }
  }
}

That is 10 lines. The Claude Code command is 2. Neither number is a study of how long a product integration takes. They are the length of the samples on this page. Restart the client after saving the file if it does not list the server. The first real call should be a search, not a portion, so the model has a food_id from the catalog. That habit is the tool-design article in this series.

Other header clients

Any client that can set a header on a streamable HTTP MCP server can use the same URL and X-API-Key. Clients that only implement OAuth use the Claude section above, not a pasted key. Clients that implement neither cannot connect. Do not publish a config for them.

After it connects

Ask for a food by name and a weight in grams. The useful trace is search_foods, then calculate_portion with the returned id. A model that answers with calories and never calls a tool is not using the server. The tool list is on the MCP page.

Personal use is the limit on this plan. The same account should not point a commercial app at these tools. That split is on the MCP page.

When the sign-in screen is the whole bug report

Work down the list before you change the URL.

The server URL is copied, not retyped. It ends in /mcp once. A second /mcp is a 404 that clients describe as unreachable.

Claude.ai, Desktop, and mobile get a browser window. No browser window means the 401 challenge is off, or the metadata URL is a different host from the MCP URL. Both have to be the public API origin.

The consent screen names the client, lists the scopes in plain language, and names the host the browser will return to. Approve only if that host is the client you started. The page will not follow a return address on a different host. Deny sends access_denied and no code.

If approval says the account does not have MCP access, the login is a REST plan or a free account. The trial starts on MCP pricing. Completing OAuth does not upgrade a plan by itself.

Claude Code and Cursor never open that screen. They send X-API-Key. The dashboard shows the full key once, when you create it. The connect panel on the API keys page inlines the key only when the value is still the plaintext key from that moment. It does not email the key, and the connect email for the subscription does not include it either. If you lost the value, create another key. Do not ask support to read it back.

A key from the wrong plan will still be accepted as a credential and then fail the tool with a plan error. That feels like a broken connector. Check the plan before you rotate the key.

Refresh tokens rotate. If a client presents an old refresh token, the server returns invalid_grant and revokes that token's family. The client should sign in again. It should not retry the same refresh token in a loop. Access tokens last about an hour. If the granted scope did not include staying connected, there is no refresh token and the hour is the whole session.

Photo tools need the vision scope on an OAuth connection. A connection that was approved for search only will fail the photo tool and name the missing scope. Reconnect and approve it. An API key does not have scopes. Photos on a key depend on the plan, which includes them for this subscription, with the caps in the rate-limit article.

Keep the key out of the URL. Query strings end up in logs, in browser history, and in the referrer of the next page. The header and the OAuth bearer token are the two places a credential belongs. The consent page reads the website login token from the browser's own storage and sends it only to the API's decision endpoint. It does not put that token on the return URL. The return URL receives an authorization code, once, which the client trades in from its own backend or loopback listener.

The same server URL is what you paste in all four places. The difference is the credential. On the MCP page the first tab is Claude: URL, streamable HTTP, OAuth, no key. The Claude Code tab is the terminal command. The Cursor tab is mcp.json. The other tab is the header, for a client that can set one and is not one of those three. The dashboard's connect panel opens on the Claude Code tab when you have just created a key, and it fills that key into the header tabs only. It does not fill the key into the Claude tab. If you see a key in the Claude instructions, you are on the wrong tab.

After the client lists the server, ask a question that needs the catalog: a named food and a weight in grams. If the answer arrives with no tool call, the model ignored the server. If the tool call is calculate_portion with an id you did not get from search_foods, the description was not enough and the call will miss. Search first. That is the whole onboarding.

Related

• Authenticating a Remote MCP Server with API Keys
• Designing MCP Tools an LLM Actually Calls Correctly
• MCP docs
• MCP pricing