Any MCP client

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. 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 — the most commonly used tool
• MCP overview — all tools with example responses