---
title: "MCP Integration Overview | Gazebo Docs"
description: "Connect Gazebo using MCP OAuth or scoped agent tokens. Find tested Cursor, Claude, ChatGPT Business web and Devin setup, plus credential-access tools."
url: "https://gazebohq.com/docs/mcp"
---

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

Gazebo exposes a hosted MCP (Model Context Protocol) server for credential retrieval. Use a remote Streamable HTTP client with MCP OAuth and Client ID Metadata Documents (CIMD) or Dynamic Client Registration (DCR), or with a custom bearer-token header. Client configuration and authentication support vary.

## Endpoint

```
https://app.gazebohq.com/api/mcp
```

With MCP OAuth, sign in to Gazebo, explicitly select the service keys to share and choose an access deadline. The connection uses the existing agent policies and grant controls; it does not grant account administration access. Disconnect it from **Settings → Developer → Consent clients → Active Grants**, or revoke its linked agent. OAuth clients can use CIMD or dynamically register a public client; neither registration method grants credential access by itself.

For manual bearer authentication, create an agent and its token at [Agents](https://app.gazebohq.com/agents) and pass it in the `Authorization` header. Account API tokens and browser sessions cannot authenticate MCP requests.

For an OAuth connection, `get_credential` must specify the approved `key_name`. Omission does not select a default key or grant access to other keys. The returned provider key remains visible to the client runtime and its host; revoking the connection only stops future retrieval.

## Available tools

### Tool metadata and permissions

Each tool advertises a human-readable title and standard MCP behavior hints:

| Tool | Display title | Read-only | Destructive | Idempotent | Open-world |
|---|---|---|---|---|---|
| `get_identity` | View connection identity and access | Yes | No | Yes | No |
| `get_credential` | Retrieve a service credential | No | No | No | No |
| `list_audit_events` | List credential-access events | Yes | No | Yes | No |

Credential retrieval is not marked read-only: valid attempts create audit events, and successful retrieval releases a sensitive value to the runtime and its host. It is not destructive because it does not modify or delete provider data. Open-world is false because these tools operate on Gazebo's stored credentials and account records, not arbitrary provider endpoints.

These hints describe behavior; they do not grant access, enforce client confirmation or guarantee safe handling of returned keys. Gazebo's authentication and retrieval policies still apply. Client permission controls vary.

### `get_identity`

Returns the calling agent's name and service/method access policy. Call this first to confirm which services are accessible before fetching credentials. No credentials or credential-access audit events are produced; ordinary operational request logging may still occur.

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

### `get_credential`

Retrieves the credential for a named service. It requires `service` and `method`. The declared method is checked against the credential-release policy; the tool does not execute that HTTP method or any provider request. OAuth requests also require an explicitly approved `key_name`. Only manual agent-token requests may omit `key_name` to select the service's primary active credential. Valid credential-access attempts (including policy denials) are logged; authentication failures and malformed arguments are not credential-access events. The actual stored provider key is delivered to the MCP client/agent; avoid persisting it.

See the [Get credential reference](https://gazebohq.com/docs/mcp/get-credential) for full documentation.

### `list_audit_events`

Returns recent credential-access attempts for the calling agent. Use `limit` from 1 through 50, and optionally filter with `service` and paginate with `cursor`. Every event includes a stable `event_id` for correlation.

```
list_audit_events({ limit: 10, service: "stripe" })
→ {
    status: "ok",
    count: 2,
    events: [
      { event_id: "...", service: "stripe", method: "POST", outcome: "success", timestamp: "..." },
      { event_id: "...", service: "stripe", method: "GET", outcome: "denied", timestamp: "..." }
    ]
  }
```

## Recommended usage pattern

```
1. get_identity()         → confirm which services are accessible
2. get_credential(...)    → fetch the credential you need
3. [use the credential]   → make your API call; do not persist the value
4. list_audit_events(...) → optionally verify the access was logged
```

## Client setup

Choose your client below. Start with `get_identity` to confirm the connection before retrieving a credential.

- [Cursor](https://gazebohq.com/docs/mcp/cursor)
- [Claude Desktop](https://gazebohq.com/docs/mcp/claude-desktop)
- [Claude Code](https://gazebohq.com/docs/mcp/claude-code)
- [ChatGPT / Codex / Responses API](https://gazebohq.com/docs/mcp/openai)
- [Devin / Windsurf](https://gazebohq.com/docs/mcp/windsurf)
- [Any MCP client](https://gazebohq.com/docs/mcp/custom)

For Claude Desktop, use the remote custom connector flow described in [Claude's official guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), not Claude Code's configuration. Add `https://app.gazebohq.com/api/mcp`, select **Sign in now**, **Use Claude's published identity**, and **Streamable HTTP**. Complete Gazebo's sign-in and approve only the keys this connection needs. Claude's connector controls and availability depend on your account. Its remote connector runs through Anthropic's infrastructure, which can receive returned credentials; this is not a local-only connection. Do not select **No sign-in** for the OAuth flow.

## Tested clients

Tested paths include **Cursor Desktop, Claude Chat, Claude Desktop, ChatGPT Business on web, Claude Code's desktop Code session, Devin hosted, Codex CLI and the OpenAI Responses API**. The latest recorded client verification is **8 November 2026**; this is not a claim that every client was retested on that date.

| Client or runtime | Recorded test scope |
|---|---|
| Cursor Desktop | macOS OAuth connection, tool discovery, identity, reported fictional-key retrieval and rejection after revocation. |
| Claude Chat | Normal Chat OAuth flow on 7 November: identity, approved fictional-key retrieval, matching audit retrieval and rejection after grant revocation. |
| ChatGPT Business — web | User-tested on 8 November: OAuth connection, identity, fictional-key retrieval and matching audit lookup. After revocation, a fresh retrieval prompted reconnection. |
| Claude Desktop | macOS remote connector OAuth flow; the earlier Desktop run covered discovery, identity, named retrieval and rejection after revocation. |
| Claude Code — desktop Code session | macOS OAuth flow on 6 November: discovery, identity, fictional-key retrieval, matching audit retrieval and rejection after revocation. |
| Devin hosted | Personal OAuth flow executed on Devin's servers, including identity, fictional-key retrieval, matching audit retrieval and rejection after revocation. |
| Codex CLI | Native app-server MCP tool calls using a scoped agent token; not a model-driven, IDE or OAuth test. |
| OpenAI Responses API | A separate model-driven test covering credential retrieval, denials, audit pagination and revoked-token failure. |

Claude Code's terminal/CLI run verified connection health and rejection after revocation, **not tool execution**. Other ChatGPT plans, native mobile clients and token refresh were not verified by the Business web test; public-directory eligibility is separate. Legacy Windsurf/Cascade remains unverified. A successful test in one runtime or authentication mode does not verify another.

See the [compatibility guide](https://github.com/gazebohq/gazebo-mcp/blob/main/docs/client-verification.md) for tested authentication methods, environments and detailed results.
