Integrate with MCPGate

This section is for developers building MCP clients — AI assistants, agent frameworks, IDE extensions, or custom tooling — that connect to MCPGate as an MCP server. It covers everything your client needs to deliver a first-class experience: tool discovery, rich metadata, safety hints, and connector status.

Not for end users

If you are an end user setting up Claude Desktop, Cursor, or another existing MCP client, see the Client Setup section instead. This section is for developers writing code that talks to MCPGate over the MCP protocol.

What MCPGate exposes to clients#

MCPGate presents itself as a standard MCP server. Your client connects once and gets access to all tools the user has enabled across every connected service. Beyond plain tools, MCPGate layers three additional surfaces:

LayerSurfacePurpose
1. AnnotationsMCP spec annotations fieldStandard safety hints: readOnly, destructive, idempotent, openWorldHint
2. Extended metadatamcpgate_tool_metadata toolRich per-tool data: risk level, category, action template for activity feeds
3. Connector discoverymcpgate_list_connectors toolLive connector status: which services are connected, account count, tool count

Authentication#

MCPGate uses OAuth 2.0 with PKCE for all client authentication. Your application registers once, directs the user through the authorization flow, and receives a short-lived JWT access token. Pass that token as a bearer token on every request to the MCP endpoint.

MCP connection header
http
Authorization: Bearer <access-token>

The OAuth server metadata is available at GET /.well-known/oauth-authorization-server and public keys for token verification at GET /oauth/jwks.

Register your client once

Before directing users through the authorization flow, register your application with MCPGate. Registration is a single POST /oauth/register call and returns a permanent client_id. See the OAuth Setup page for the full flow.

Quick example — a tool with annotations#

When your client calls tools/list, each tool in the response includes an annotations object. Here is what a Gmail read tool looks like:

tools/list response (excerpt)
json
{
  "name": "gmail_read_email",
  "description": "Fetch a Gmail message by ID and return its headers and body.",
  "inputSchema": { ... },
  "annotations": {
    "title": "Read Email",
    "readOnly": true,
    "idempotent": true,
    "destructive": false,
    "openWorldHint": true
  }
}

Your client can use readOnly: true to auto-approve this tool without prompting the user, while surfacing destructive: true tools with an explicit confirmation dialog. See Tool Annotations for the full mapping.

Next steps#