Quick Start: Claude Code MCP

From Claude Code you can wire live Amazon data into the loop you already work in — query Ads, Seller Central, and Vendor Central while you build, prototype an agent against real campaigns, or debug a listing without leaving the terminal.

Use Claude Code MCP when you want Claude Code to connect directly to tools, databases, APIs, monitoring systems, issue trackers, or your private MCP server.

For the official reference, see Connect Claude Code to tools via MCP in the Claude Code docs.

Your MCP server hostname is private to your deployment. It comes from your cloud provider, belongs to your environment, and is not shared across customers. Replace {your-private-mcp-host} with the private host shown in your dashboard.

Add a remote HTTP server

Remote HTTP is the recommended transport for cloud-hosted MCP servers.

export MCP_API_KEY="mcp_live_..."

claude mcp add --transport http private-mcp https://{your-private-mcp-host}/mcp \
  --header 'Authorization: Bearer ${MCP_API_KEY}'

Keep the single quotes around the header so Claude Code stores the environment-variable reference instead of your raw key.

When you configure MCP servers through .mcp.json, ~/.claude.json, or claude mcp add-json, the type field can use either http or streamable-http.

Add a remote SSE server

SSE is deprecated. Use HTTP when the server supports it. If you must connect an older SSE server:

claude mcp add --transport sse legacy-api https://api.example.com/sse \
  --header 'Authorization: Bearer ${MCP_API_KEY}'

Add a local stdio server

Stdio servers run as local processes. Use them for tools that need local system access or custom scripts.

claude mcp add --transport stdio --env TOOL_API_KEY="${TOOL_API_KEY}" local-tool \
  -- npx -y local-tool-mcp-server

All Claude flags such as --transport, --env, --scope, and --header must come before the server name. The -- separator marks the start of the command and arguments passed to the MCP server.

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server's environment to the project root. Local servers can read it to resolve project-relative paths.

Manage servers

Use the Claude Code CLI for saved configuration:

claude mcp list
claude mcp get private-mcp
claude mcp remove private-mcp

Use /mcp inside Claude Code to inspect live server status, authenticate with OAuth servers, retry failed connections, and see connected tool counts.

Claude Code refreshes tool, prompt, and resource lists when servers send MCP list_changed notifications. HTTP and SSE servers reconnect automatically with backoff after transient disconnects. Stdio servers are local processes and are not automatically reconnected.

Choose a scope

The --scope flag controls where the server is stored and who can use it.

Local scope is the default. Use it for personal or experimental servers. Use project scope for team-shared server entries that should be checked into version control. Use user scope for personal tools you want across projects.

Examples:

claude mcp add --transport http private-mcp --scope local https://{your-private-mcp-host}/mcp
claude mcp add --transport http private-mcp --scope project https://{your-private-mcp-host}/mcp
claude mcp add --transport http private-mcp --scope user https://{your-private-mcp-host}/mcp

When the same server name exists in more than one scope, Claude Code uses the highest-precedence definition: local, project, user, plugin-provided servers, then Claude.ai connectors.

Use project JSON

Project-scoped MCP servers live in .mcp.json:

{
  "mcpServers": {
    "private-mcp": {
      "type": "http",
      "url": "https://{your-private-mcp-host}/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_API_KEY}"
      }
    }
  }
}

Claude Code supports environment-variable expansion in .mcp.json values:

• ${VAR} expands to the environment variable value.
• ${VAR:-default} uses a default when the variable is unset.

Expansion works in command, args, env, url, and headers. If a required variable is missing and no default is provided, Claude Code fails to parse the config.

For project-scoped servers, Claude Code prompts for approval before using servers from .mcp.json. To reset those choices, run:

claude mcp reset-project-choices

Add JSON directly

Use claude mcp add-json when you already have a JSON server definition:

claude mcp add-json private-mcp '{
  "type": "http",
  "url": "https://{your-private-mcp-host}/mcp",
  "headers": {
    "Authorization": "Bearer ${MCP_API_KEY}"
  }
}'

Authenticate remote servers

For bearer-token servers, pass a header when adding the server or store it in JSON config.

For OAuth servers, add the server first, then run /mcp inside Claude Code and follow the authentication flow. Claude Code can use fixed OAuth callback ports and preconfigured OAuth settings when your environment requires them.

Plugin-provided MCP servers

Claude Code plugins can bundle MCP servers. Plugin servers start when the plugin is enabled and appear alongside manually configured servers in /mcp.

If you enable or disable a plugin during a session, run:

/reload-plugins

Plugin-provided MCP servers are managed through plugin installation rather than claude mcp commands.

Output limits

Claude Code warns when MCP tool output exceeds 10,000 tokens. To raise the limit for a session:

MAX_MCP_OUTPUT_TOKENS=50000 claude

Keep tool outputs focused when possible. Large tool responses increase context pressure and make later turns harder to reason about.

Tool search and prompts

Claude Code can defer large MCP tool lists through tool search, which helps scale when many servers expose many tools. If a server is still connecting when a request needs it, Claude waits while the relevant server becomes available.

MCP prompts can also appear as Claude Code commands. Use prompt commands when the server provides reusable workflows in addition to tools.

Managed configuration

Enterprise admins can manage MCP configuration through managed settings. Managed configuration can exclusively control available servers or use allowlists and denylists to restrict which command-based or URL-based servers users may add.

Use managed configuration for organization-wide compliance, approved server catalogs, and consistent access rules.

Troubleshooting

Server does not appear

Run claude mcp list, then open /mcp inside Claude Code. If the server name is workspace, rename it; Claude Code reserves that name for internal use.

Authentication fails

Confirm MCP_API_KEY is exported in the shell that launches Claude Code, or re-authenticate OAuth servers through /mcp.

Project server prompts for approval

That is expected for servers loaded from .mcp.json. Review the config and approve the server if you trust it.

Tool output is too large

Filter the tool call if possible, or start Claude Code with a larger MAX_MCP_OUTPUT_TOKENS value.

Remote server disconnects

Open /mcp and retry the server. HTTP and SSE transports reconnect automatically for transient errors, but authentication and not-found errors require config changes.

Next steps

For a shorter setup path focused only on your private MCP server, see the Claude quick start. For reusable Claude Code workflows, see the Claude Code Skills quick start.