Copy page

Connect Clients

Connect Claude Code

Claude Code is Anthropic's command-line coding agent. It speaks the MCP Streamable HTTP transport natively and handles the OAuth flow against the gateway in your browser.

Prerequisites

• A Zuplo MCP Gateway project with at least one Virtual MCP server. See the quickstart if you haven't created one.
• Claude Code installed and signed in. Install instructions are at code.claude.com.

Add the gateway

From a terminal, run claude mcp add with the http transport, a friendly name for the server, and your Virtual MCP URL:

Code
claude mcp add --transport http zuplo https://{deploymentUrl}/v1/mcp/{slug}

The name (zuplo above) is the identifier you'll see in /mcp and in any prompts that invoke the server. Pick whatever makes sense for your team.

By default the server is registered at local scope for the current project. Use --scope user to make it available across every project on your machine, or --scope project to commit a .mcp.json file alongside your code so your whole team picks it up:

Code
# Share with the team via .mcp.json in the repo root
claude mcp add --transport http --scope project zuplo https://{deploymentUrl}/v1/mcp/{slug}

Once added, the configuration is written to one of:

• ~/.claude.json (local or user scope)
• .mcp.json at the project root (project scope)

You can also edit either file directly. The HTTP server entry has this shape:

.mcp.json
{
  "mcpServers": {
    "zuplo": {
      "type": "http",
      "url": "https://{deploymentUrl}/v1/mcp/{slug}"
    }
  }
}

Authenticate

The first time Claude Code talks to the gateway, the gateway returns 401 Unauthorized and Claude Code marks the server as needing authentication.

1. Inside a Claude Code session, run the /mcp slash command:

   Code
   /mcp

2. Select the gateway entry and follow the browser prompt. Claude Code opens the gateway's OAuth flow, you sign in with your identity provider, and the gateway returns the access token to Claude Code.

3. The gateway then displays the consent page listing every upstream MCP server the Virtual MCP depends on. Click Connect for each upstream and complete the upstream OAuth flow, then click Authorize to finish.

4. Back in the terminal, run /mcp again to confirm the server is connected and to see the tool count.

Access tokens are stored securely (in the system keychain on macOS, in a credentials file on other platforms) and refresh automatically. To revoke access, open /mcp and choose Clear authentication for the server.

Use a fixed OAuth callback port

By default, Claude Code picks a random local port for the OAuth callback. The gateway accepts any loopback redirect URI by default, so this works out of the box. If you have a strict identity provider that requires a fixed redirect URI registered in advance, pass --callback-port:

Code
claude mcp add --transport http --callback-port 8080 \
  zuplo https://{deploymentUrl}/v1/mcp/{slug}

Use pre-configured OAuth credentials

The gateway supports Dynamic Client Registration (DCR), so Claude Code registers itself automatically. If you operate a strict environment that requires pre-registered OAuth clients instead, register an OAuth app with the gateway's identity provider, then pass the credentials when you add the server:

Code
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  zuplo https://{deploymentUrl}/v1/mcp/{slug}

The --client-secret flag prompts for the secret with masked input. Claude Code stores the secret in the system keychain, not in the config file.

For non-interactive scripts, set the secret via the MCP_CLIENT_SECRET environment variable instead of the prompt:

Code
MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  zuplo https://{deploymentUrl}/v1/mcp/{slug}

What Claude Code supports

Claude Code uses OAuth 2.1 with PKCE and registers itself via Dynamic Client Registration. It supports the following MCP capabilities from the gateway:

• Tools — invoke gateway-exposed tools during a session.
• Prompts — surface prompts as /mcp__<server>__<prompt> slash commands.
• Resources — reference resources with @server:protocol://path in prompts.
• Roots — declare the project root to the server.
• Elicitation — Claude Code shows form dialogs and opens URLs when a server requests structured input or interactive authorization mid-task.

Manage the connection

A few commands you'll use often:

Code
# List every configured server
claude mcp list

# Show details for one server
claude mcp get zuplo

# Remove the server
claude mcp remove zuplo

Inside a session, /mcp shows the live status of each server (connected, pending, failed), the number of tools each one exposes, and provides re-authentication and authentication-clearing commands per server.

Troubleshooting

• /mcp shows the server as failed. Run claude mcp get zuplo to confirm the URL is correct, then re-run /mcp to retry. Check the gateway's deployment is healthy and the URL is reachable from your machine.
• "Incompatible auth server: does not support dynamic client registration." This appears if the gateway's identity provider blocks DCR. Either enable DCR on the provider or use pre-configured OAuth credentials as shown above.
• The browser does not open during OAuth. Copy the URL Claude Code prints in the terminal and open it manually. If the callback fails, paste the full callback URL from your browser's address bar into the prompt Claude Code shows.

Related

• Connect MCP clients overview
• Anthropic's docs: Connect Claude Code to tools via MCP
• Authentication overview