New: watch your coding agents work, step by step, on a live board. Try the demo, no account

Taskhold

Add a remote MCP server to Claude Code

Claude Code adds remote servers from the command line. claude mcp add with --transport http writes the entry for you, and the scope you pick decides which file it lands in and who else gets it.

By Jake Marsh. Checked against Claude Code's own docs on 2026-10-31; each section links its source.

The Claude Code config

For a server named my-server at https://example.com/mcp that takes an Authorization header. Where it goes: Run in a terminal (--scope user makes it available in every project).

claude mcp add --transport http --scope user my-server "https://example.com/mcp" --header "Authorization: Bearer YOUR_KEY"

Swap in your own server below and the Claude Code version updates first, with every other client after it.

Where Claude Code reads it

  • ~/.claude.json, under the project's pathlocal (the default): this project, only you
  • .mcp.json in the project rootproject: everyone who clones the repo, through version control
  • ~/.claude.jsonuser: every project, only you

Source: code.claude.com/docs/en/mcp

Keys, headers and sign-in

A static key goes in a header: --header "Authorization: Bearer ..." on the command (or -H). In .mcp.json, Claude Code expands ${VAR} and ${VAR:-default} in a remote server's url and headers, so a file you commit can name the variable while each person keeps the key in their own environment.

For a server that signs you in with OAuth, leave the header off. Run /mcp in a session, or claude mcp login <name> from your shell, to sign in.

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${MY_SERVER_KEY}" }
    }
  }
}
.mcp.json with the key read from MY_SERVER_KEY. An unset variable with no default loads as the literal ${MY_SERVER_KEY} text, with a missing-variable warning.

Source: code.claude.com/docs/en/mcp

Check that it connected

claude mcp list shows a status for each server: Connected, Needs authentication or Failed to connect. claude mcp get <name> adds an Issue: line when something is wrong. Inside a session, /mcp shows each server's status and tool count, and is where you sign in.

Source: code.claude.com/docs/en/mcp

Claude Code gotchas

  • An entry with a url but no type is a configuration error. Claude Code reads it as a stdio server, skips it and reports that the server has a "url" but no "type". Hand-written .mcp.json entries need "type": "http".

    Source: code.claude.com/docs/en/mcp

  • Project servers from .mcp.json wait for your approval in an interactive session, and claude mcp list shows them as pending until you run claude and approve them. claude mcp reset-project-choices clears earlier choices.

    Source: code.claude.com/docs/en/mcp

  • Some credential variables read as empty in a remote server's url and headers, including ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and NPM_TOKEN, so Bearer ${ANTHROPIC_AUTH_TOKEN} sends Bearer with nothing after it. Copy the value into a variable with your own name.

    Source: code.claude.com/docs/en/mcp

  • claude mcp add saves without checking the key, so a placeholder only fails later, at connect time. And when the server rejects a configured Authorization header, Claude Code reports the connection as failed instead of falling back to OAuth: remove the header to sign in instead.

    Source: code.claude.com/docs/en/mcp

Still not connecting? Claude Code MCP server not connecting walks through the fixes in order.

Generate the config for your server

Runs in your browser. Nothing you type is sent anywhere. Still, don't paste real keys on shared screens.

The header value is never put in the link.

Claude Code

Run in a terminal (--scope user makes it available in every project)

claude mcp add --transport http --scope user my-server "https://example.com/mcp" --header "Authorization: Bearer YOUR_KEY"

Source: code.claude.com/docs/en/mcp

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)

{
  "mcpServers": {
    "my-server": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Source: cursor.com/docs/context/mcp

Codex CLI

~/.codex/config.toml

[mcp_servers.my_server]
url = "https://example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }

Source: developers.openai.com/codex/mcp

Windsurf / Devin Desktop

~/.config/devin/mcp_config.json (older Windsurf: ~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "my-server": {
      "serverUrl": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Source: docs.devin.ai/windsurf/plugins/cascade/mcp

Devin CLI / Devin Local

Run in a terminal (-s user saves it to ~/.config/devin/mcp_config.json for every project)

devin mcp add -s user -H "Authorization: Bearer YOUR_KEY" my-server "https://example.com/mcp"

Source: docs.devin.ai/cli/extensibility/mcp/configuration

VS Code (Copilot agent mode)

.vscode/mcp.json in the workspace, or your user mcp.json (MCP: Open User Configuration)

{
  "servers": {
    "my-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Source: code.visualstudio.com/docs/agents/reference/mcp-configuration

Gemini CLI

~/.gemini/settings.json (or .gemini/settings.json in the project)

{
  "mcpServers": {
    "my-server": {
      "httpUrl": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Source: geminicli.com/docs/tools/mcp-server/

Antigravity CLI (agy)

~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in the workspace)

{
  "mcpServers": {
    "my-server": {
      "serverUrl": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Source: antigravity.google/docs/mcp

Cline

cline_mcp_settings.json (in the Cline panel, MCP Servers > Configure > Configure MCP Servers; Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json)

{
  "mcpServers": {
    "my-server": {
      "type": "streamableHttp",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Source: docs.cline.bot/mcp/mcp-overview

OpenCode

opencode.json in the project root, or ~/.config/opencode/opencode.json for every project

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-server": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Source: opencode.ai/docs/mcp-servers/

Need a task list for those agents?

Taskhold is a remote MCP server that gives Claude Code and your other agents a task list you share, with their progress on a live board. Its setup link writes this config for the agent, so you don't have to. $12 a month or $120 a year, 7-day trial.

Start my 7-day trialTry the live board, no accountTaskhold setup for Claude Code

Other clients