---
title: "Claude Code MCP Setup | Gazebo Docs"
description: "Connect Gazebo to Claude Code using the desktop OAuth connector or terminal bearer-token configuration. Review tested paths and retrieve approved credentials."
url: "https://gazebohq.com/docs/mcp/claude-code"
---

> Documentation index: [llms.txt](https://gazebohq.com/docs/llms.txt). Markdown versions are available by appending `.md` to documentation page URLs.

Add Gazebo to Claude Code as an MCP server so it can retrieve credentials from your vault during coding sessions.

## Prerequisites

- A Gazebo account with at least one service connected
- For the desktop connector: Claude Code access and permission to approve selected keys in Gazebo
- For terminal configuration: an agent created in Gazebo with a bearer token

## Desktop connector

In Claude's **Code** tab, start a local session in a separate test folder. Open **+ → Connectors**, then add or reconnect Gazebo using `https://app.gazebohq.com/api/mcp`. Complete Gazebo's OAuth sign-in and approve only the service keys this connection needs. An existing Gazebo connector may already appear in the menu.

Start with `get_identity`. OAuth credential retrieval must include the approved `key_name`. Use a fictional key for the first retrieval, check its event with `list_audit_events`, then revoke the grant in Gazebo and confirm a fresh request fails without reconnecting.

The Code tab and normal Chat mode are different test surfaces, even when they share an account connector. Selecting **This computer** does not make the remote connector local-only: Anthropic's connector infrastructure can receive returned credentials.

## Terminal configuration

In Claude Code's MCP server configuration, add Gazebo with endpoint `https://app.gazebohq.com/api/mcp` and the header `Authorization: Bearer <your-agent-token>`. Create the agent bearer token at [Gazebo Agents](https://app.gazebohq.com/agents).

For a project `.mcp.json`, the current documented HTTP configuration is:

```json
{
  "mcpServers": {
    "gazebo": {
      "type": "http",
      "url": "https://app.gazebohq.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GAZEBO_AGENT_TOKEN}"
      }
    }
  }
}
```

Set `GAZEBO_AGENT_TOKEN` in the environment inherited by Claude Code. Do not put the real token in a committed file. Note that Claude Code uses `${NAME}` interpolation, unlike Cursor's `${env:NAME}`. See [Claude Code's current MCP documentation](https://code.claude.com/docs/en/mcp). Configuration was checked against that documentation; it is not a completed runtime test of your installed release.

Use the current Claude Code documentation for terminal configuration rather than assuming that the desktop connector's setup applies to the CLI.

## Tested status

**Claude Code has a tested desktop OAuth path.** Identity, named fictional-key retrieval, matching audit retrieval and fresh-request rejection after revocation passed on 6 November 2026.

See the [compatibility guide](https://github.com/gazebohq/gazebo-mcp/blob/main/docs/client-verification.md) for the macOS test environment and evidence limits. Terminal/CLI tool execution, token renewal, timed expiry and marketplace-plugin installation remain unverified; the earlier CLI check covered connection health only.

## Verify the connection

Ask Claude to call `get_identity`:

```
get_identity()
→ {
    status: "ok",
    name: "claude-dev",
    accessible_services: [
      { service: "github", allowed_methods: ["GET"] },
      { service: "stripe", allowed_methods: ["GET", "POST"] }
    ]
  }
```

## Retrieve a credential

```
get_credential({ service: "github", key_name: "token", method: "GET" })
→ "<actual-stored-provider-key>"
```

Claude Code receives the actual provider credential. The declared method controls retrieval; the provider key's permissions control subsequent GitHub API calls. Do not persist the returned value. Revoking Gazebo access blocks new retrieval, not use of a key already received.

## Usage guidance for Claude

Claude works well with Gazebo when given context about what it's allowed to do. You can prompt it directly:

> "Use the Gazebo MCP server to get my GitHub token, then list the open issues on my repo."

Claude will call `get_identity` to confirm access, then `get_credential` to retrieve the token, then use it for the GitHub API call.

## Troubleshooting

**MCP server not appearing** — Confirm the Claude Code MCP configuration follows Claude Code's current documentation and that the endpoint and header are correct.

**`401 Unauthorized`** — Token is wrong or the agent was deleted. Check the Gazebo dashboard.

**Denial on `get_credential`** — The method you requested isn't in the agent's access profile. Update the profile in the Gazebo dashboard.
