API Reference

mcpgate exposes one MCP-compliant endpoint plus REST APIs for health and admin. The MCP endpoint is what AI clients talk to; the REST surface is what operators use.

MCP endpoint

POST /mcp

The primary integration point for AI clients. Implements the Model Context Protocol with HTTP transport and OAuth 2.0 bearer-token authentication (RFC 6750).

Protocol versions

Negotiated per session via the MCP-Protocol-Version request header or the initialize / server/discover method. mcpgate advertises five:

• 2024-11-05, 2025-03-26, 2025-06-18 — older stable revisions, served on request.
• 2025-11-25 — current stable; default for clients that do not request a draft.
• 2026-07-28 — the upcoming stateless-core draft (RC locked May 21 2026, finalising late July 2026). Served only when a client explicitly lists it. See When a tool call takes minutes for the rollout story.

A client that does not name the draft never gets pushed onto it; an older client connecting today behaves exactly as it did before the draft work shipped.

Methods

Beyond the standard MCP surface (initialize / server/discover, tools/list, tools/call, resources/list, resources/read), the draft adds:

• tasks/get — poll a long-running tool call that came back as a task handle.
• tasks/cancel — cancel a running task.
• Multi-round-trip input_required — the protocol-level mechanism behind elicitation. A tool call can return resultType: "input_required" with an asked-for shape; the client answers, the call resumes.

A tool call promotes to a task on the server side when it exceeds the configured promotion budget (default 8 seconds, operator-tunable). The client opts in to the Tasks shape once via capability negotiation; from then on any single call may come back inline or as a task handle.

Authentication

All MCP requests require a Bearer token obtained via the OAuth 2.0 flow:

# 1. Discover OAuth endpoints
GET /.well-known/oauth-authorization-server

# 2. Authorize (browser redirect)
GET /auth/authorize?client_id=...&redirect_uri=...&response_type=code

# 3. Exchange code for token
POST /auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=...&redirect_uri=...

AI clients (Claude, ChatGPT, Codex, Gemini) handle the flow automatically when configured. mcpgate also implements RFC 7591 Dynamic Client Registration for clients that prefer to register on first connect rather than out-of-band.

Tool naming pattern

mcpgate uses a two-tool pattern per connected service:

• <service>_read_actions — read operations
• <service>_write_actions — mutating operations

Each tool takes an action parameter naming the specific action plus the action’s own arguments. So jira_read_actions with action: "get_issue" reaches Jira’s issue endpoint, jira_write_actions with action: "create_issue" creates one.

Plus a small set of gateway tools that are not tied to any one upstream:

• gateway_info — the gateway introduces itself and its current capability surface.
• gateway_search_actions — BM25 search over the full action catalog including the long-tail surface from OpenAPI imports. See Dynamic action discovery.
• gateway_get_logs — admin-only; tail the in-memory app log for the current process.
• company_context_read — search the operator-curated Context Map (BM25) or fetch a single page by id. Returns matching page snippets plus the always-in-context auto-built index. See Context Map.
• company_context_write — create / replace / delete a Context Map page. Every write passes a shared leak-scan + size/format + attribution gate; in repo mode the gateway commits and pushes through its own identity. The index auto-rebuilds from the pages — the tool does not set it directly.

Action classification

Every action carries a classification that decides what the executor does with the call:

The MCP spec also defines an optional destructiveHint annotation; mcpgate’s enforcement does not rely on it. Vendor-shipped annotations are advisory, not authoritative; the gateway classifies from rule-based category policies that match against action name, method, endpoint and description, so covered actions get the appropriate classification regardless of what the upstream vendor declared.

Connected services

Each connected service registers its read and write tools at startup. Only services with valid credentials appear in the tools/list response. For the canonical, always-current catalog of services and their connectors, see Services.

REST endpoints

The non-MCP surface, used by operators (not by AI clients):

Health check

Plain GET, returns the gateway version and component status. Use for liveness probes:

GET /health

{
  "status": "healthy",
  "version": "2.0.1330",
  "timestamp": "2026-06-14T20:01:52.909306",
  "components": {
    "redis": { "status": "up", "latency_ms": 1.4 }
  }
}

The version field follows 2.0.<revision>. The number bumps on every code merge; readiness for upgrade is communicated through the changelog, not the bare version.

Tool discovery

AI clients discover available tools via the MCP tools/list method. The default list is curated — the actions hand-picked per service for clarity and ergonomics. Most services carry a much larger long-tail auto-generated from their OpenAPI spec. Those long-tail actions are not shipped in tools/list; the model finds them on demand via gateway_search_actions and pulls a definition only when a query matches. See Dynamic action discovery for the full reference.

Related

• Services — canonical list of connectors
• Compliance — audit log, PII, throughput, hooks
• Access Model — roles, permissions, audit and the RBAC answer
• Dynamic action discovery — BM25 long-tail search
• When a tool call takes minutes — the 2026-07-28 protocol revision rollout
• Destructive-action governance — the high-risk-action model behind the classification