# Connect Claude Code

[Claude Code](https://code.claude.com/) 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](../quickstart.mdx) if you haven't created one.
- Claude Code installed and signed in. Install instructions are at
  [code.claude.com](https://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:

```bash
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:

```bash
# 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:

```json title=".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:

   ```text
   /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`:

```bash
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)](../auth/overview.mdx),
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:

```bash
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:

```bash
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:

```bash
# 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](./overview.mdx)
- Anthropic's docs:
  [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
- [Authentication overview](../auth/overview.mdx)