---
title: "Any MCP Client | Gazebo Docs"
description: "Connect remote Streamable HTTP MCP clients using OAuth with CIMD or DCR, or scoped bearer headers. Review authentication and credential-handling requirements."
url: "https://gazebohq.com/docs/mcp/custom"
---

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

Gazebo works with remote Streamable HTTP clients using MCP OAuth with Client ID Metadata Documents (CIMD) or Dynamic Client Registration (DCR), or custom bearer headers. Local stdio needs an HTTP bridge.

## Connection details

Configure your client with the endpoint `https://app.gazebohq.com/api/mcp`. For OAuth, let the client discover Gazebo's sign-in settings and complete the approval flow. For manual bearer authentication instead, supply an `Authorization: Bearer <your-agent-token>` header using a token created at [Agents](https://app.gazebohq.com/agents). Client configuration formats differ, so follow the client's current documentation for the appropriate configuration location and field names.

## How clients discover tools

The client first sends `initialize`, accepts the negotiated protocol version, then sends `notifications/initialized`. It can then call `tools/list` to discover:

- `get_identity` — returns the agent's name and access policy
- `get_credential` — retrieves a credential for a named service
- `list_audit_events` — returns recent access events for this agent

## Transport

Gazebo uses stateless, JSON-only Streamable HTTP over `POST`. It does not offer SSE, sessions, or server streaming. `GET` and session `DELETE` return `405 Method Not Allowed`; accepted notifications return `202 Accepted` with no body. Clients should accept both `application/json` and `text/event-stream`, even though Gazebo replies with JSON.

The server negotiates supported protocol versions during initialization. Send the negotiated `MCP-Protocol-Version` header on subsequent requests; an unsupported explicit version returns `400`. An MCP `ping` request returns an empty result.

Native clients normally omit `Origin`. Browser clients that send `Origin` must use an origin explicitly allowed by the Gazebo deployment; an untrusted origin returns `403`. CORS permission alone is not authentication.

## Authentication

MCP requests authenticate with `Authorization: Bearer <token>`: either a manual agent token or a resource-bound MCP OAuth access token. Missing or invalid authentication returns `401` with a `WWW-Authenticate` discovery challenge. The protected resource metadata identifies the authorization server, whose metadata is served at `/.well-known/oauth-authorization-server` on the same origin.

OAuth clients use the authorization-code flow with S256 PKCE, their HTTPS CIMD URL or dynamically issued ID as `client_id`, and `https://app.gazebohq.com/api/mcp` as the `resource`. Redirects must match the client's registration; native HTTP loopback callbacks may vary only their port. Gazebo requires signed-in, same-origin user approval and an explicit selection of available keys. Access tokens expire and refresh tokens rotate; refresh-token reuse disconnects the connection. Account API tokens, signed REST-consent tokens and browser sessions cannot authenticate MCP requests.

Clients discover the `registration_endpoint` in Gazebo's authorization-server metadata. Send JSON with `redirect_uris` and `token_endpoint_auth_method: "none"`; `client_name` is optional. Supported callbacks are HTTPS or HTTP loopback URLs, without fragments, embedded credentials or wildcards. Gazebo registers public clients for authorization-code and rotating-refresh flows and issues no client secret. Registration is rate-limited and does not approve access, create an agent or release credentials. Application names are self-supplied, not verified endorsements. Updating registration metadata through RFC 7592 is not supported; register a new client when callbacks change.

The existing agent policies still govern service access and declared HTTP methods. OAuth additionally limits the connection to its approved named keys; `get_credential` must include `key_name`. These policies control credential retrieval, not subsequent provider API calls.

## Credential handling

`get_credential` delivers the actual provider credential to the MCP client/agent. Its host, and any gateway proxying tool responses, can access that value. Use trusted clients and narrow provider permissions; do not persist returned credentials in files, environment variables, logs, prompts, or long-lived memory. A client's transcript or model context may contain tool responses.

The declared HTTP method controls credential retrieval, not subsequent provider API calls. Revocation blocks future retrieval; a key already received remains usable until revoked or rotated at the provider.

## Tool outcomes

MCP tool results are wrapped in `result.content` as text. Structured values such as identity, audit pages, denials and not-found outcomes are JSON-encoded inside that text. A successful credential is the plaintext text value, not a JSON-RPC result object containing a `credential` field.

Policy denials and missing credentials return HTTP `200` with `result.isError: true` and a structured status in the text content. Invalid arguments use a JSON-RPC error; authentication failure uses HTTP `401`. Do not confuse these responses with the separate REST API's HTTP status conventions.

## Tool reference

See the individual tool pages for full documentation:

- [Get credential reference](https://gazebohq.com/docs/mcp/get-credential) — the most commonly used tool
- [MCP overview](https://gazebohq.com/docs/mcp) — all tools with example responses
