Claude custom connector with an API key: headers or mcp-remote

Your MCP server takes an API key in an Authorization header. Claude's custom connector dialog mostly talks about OAuth. This guide shows where the key goes, what Claude sends, and what to do when the field you need is missing. Checked against Claude's connector docs and the mcp-remote README on 2026-11-07.

The examples use https://fetchmcp.net/mcp as the server URL and YOUR_KEY as the key. Any remote MCP server that reads a bearer key works the same way.

Pick the route first

Open the Add custom connector dialog and look for a Request headers section.

Request header authentication is in beta and only a limited set of organizations has it, according to Claude's docs. If the section is not there, your organization does not have access yet. Nothing you change in the dialog will make it appear.

Route 1: No sign-in plus a Request header

1. Open Customize > Connectors and click Add custom connector. On Team and Enterprise, an Owner goes to Organization settings > Connectors, then Add, then Custom, and picks Web if asked.
2. Enter https://fetchmcp.net/mcp as the server URL. It must be an HTTPS address.
3. Set Authentication to No sign-in. This is the option the docs name for servers that use an API key.
4. Open Request headers and choose authorization from the list.
5. Enter the value as Bearer YOUR_KEY, with the space.
6. Mark the header Required, then click Add.

Bearer is the step people miss. Claude sends the value exactly as entered and adds no scheme. Type only the key and the server receives Authorization: YOUR_KEY, which most bearer-token servers reject.

Required matters at connect time. A required header with no stored value makes the connection fail. An optional header with no value is left out of the request.

authorization, x-api-key and x-auth-token are on the built-in list, and every connector can use them. A header name of your own needs Anthropic's approval first. An unapproved name makes the save fail with an error. You can add up to four headers.

Advanced > Transport stays as it is unless the server's docs say otherwise. A URL that ends in /sse picks the older SSE transport, so use the Streamable HTTP URL your server documents.

What the header means on Team and Enterprise

Request headers are set once, by whoever adds the connector. On Team and Enterprise that is an Owner, or on Enterprise a member whose custom role covers the organization's libraries. Members then connect to the connector the Owner added.

That means every member sends the same key. The docs say headers suit services where the whole organization shares one credential, such as a service account. If each person needs their own account, the docs point to OAuth instead.

Before you add a shared key, decide whose key it is.

Changing the key later

Edit covers the connector's name and URL only. Claude does not let you change authentication settings after the connector is added, and request headers count as authentication settings.

To rotate a key:

1. Create the new key on the server side.
2. Remove the connector.
3. Add it again with Bearer NEW_KEY in the header.
4. On Team and Enterprise, tell members to reconnect.
5. Revoke the old key once the new connector works.

Claude also does not show a header value again after you save it. Keep the key in your secret store, not in your head.

Route 2: the mcp-remote bridge

mcp-remote is a small Node.js program that lets a client which only runs local stdio servers reach a remote one. It needs Node 18 or later. Claude Desktop uses the system Node, even if a newer version is installed elsewhere.

Add this to claude_desktop_config.json. On macOS the file is in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\.

{
  "mcpServers": {
    "fetchmcp": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://fetchmcp.net/mcp",
        "--header", "Authorization:${AUTH_HEADER}",
        "--transport", "http-only"
      ],
      "env": { "AUTH_HEADER": "Bearer YOUR_KEY" }
    }
  }
}

Authorization:${AUTH_HEADER} has no space after the colon on purpose. The README notes that Claude Desktop on Windows, Cursor and Codex CLI do not escape spaces inside args when they start npx. The full value, space included, goes in env, where spaces are safe.

--transport http-only makes the bridge use Streamable HTTP and fail if the server does not support it. The default, http-first, tries HTTP and falls back to SSE on a 404.

Quit and restart Claude Desktop after the edit. This route is per machine and per person, so each member can use their own key. The setup pillar has the same entry next to the Claude Code, Cursor and VS Code forms.

Check that it worked

1. Open a new chat, click +, then Connectors, and make sure the connector is on for that chat.
2. Ask Claude to call a tool that does no real work.
3. If the call fails with an auth error, check the Bearer prefix first, then the key itself.

The authentication guide covers what a 401 from an MCP server usually means.

Try it with a real server

FetchMCP API runs a remote MCP server that takes Authorization: Bearer <key>, the same key as its REST API, so both routes above work with it. The MCP server registers 2 tools. get_account_status returns your credits, plan and rate limit and is free, which makes it a good first call in the check above. get_page_contents then reads one public URL per call. Failed fetches cost 0 credits.

Copy the current config from the MCP docs and request a key. Companies and individual professionals can sign up. Only Business, Enterprise and Custom sign-ups are reviewed before checkout, usually within 1 business day.