API Reference

mcpgate exposes an MCP-compliant endpoint plus REST APIs for health, admin, and OAuth.

MCP Endpoint

POST /mcp

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

Supports: tools/list, tools/call, resources/list, resources/read.

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 this flow automatically when configured.

Tool schema

mcpgate uses a two-tool pattern per service: a read tool and a write tool.

Read tools

Safe, read-only operations. Annotated with readOnlyHint: true.

{
  "name": "jira_read_actions",
  "description": "Jira READ tool with strict action validation",
  "inputSchema": {
    "type": "object",
    "properties": {
      "action": {
        "type": "string",
        "enum": ["get_issue", "list_issues", "search_issues", "get_comments", ...]
      },
      "query": { "type": "string" },
      "issue_key": { "type": "string" }
    },
    "required": ["action"]
  }
}

Write tools

Mutating operations. Annotated with destructiveHint: true. Pre-hooks can require confirmation.

{
  "name": "jira_write_actions",
  "description": "Jira WRITE tool with strict action validation",
  "inputSchema": {
    "type": "object",
    "properties": {
      "action": {
        "type": "string",
        "enum": ["create_issue", "update_issue", "add_comment", "transition_issue", ...]
      },
      "project": { "type": "string" },
      "summary": { "type": "string" },
      "description": { "type": "string" }
    },
    "required": ["action"]
  }
}

Available services

Each configured service registers its read/write tools at startup. See Services for the full list.

Service	Read tool	Write tool	Actions
Google Workspace	`google_workspace_read_actions`	`google_workspace_write_actions`	~90
Jira	`jira_read_actions`	`jira_write_actions`	22
GitLab	`gitlab_read_actions`	`gitlab_write_actions`	30+
Slack	`slack_read_actions`	`slack_write_actions`	15+
Notion	`notion_read_actions`	`notion_write_actions`	20+
Figma	`figma_read_actions`	`figma_write_actions`	10+
Grafana	`grafana_read_actions`	`grafana_write_actions`	10+
Home Assistant	`home_assistant_read_actions`	`home_assistant_write_actions`	10+
Joan	`joan_read_actions`	`joan_write_actions`	10+
Amplitude	`amplitude_mcp_read_actions`	`amplitude_mcp_write_actions`	10+
Metabase	`metabase_read_actions`	`metabase_write_actions`	10+
Sentry	`sentry_read_actions`	`sentry_write_actions`	8+
WordPress	`wordpress_read_actions`	`wordpress_write_actions`	10+

REST endpoints

Endpoint	Method	Auth	Purpose
`/health`	GET	None	Health check with version and component status
`/mcp`	POST	Bearer	MCP protocol endpoint
`/connections`	GET	Session	OAuth dashboard for service connections
`/admin/reload`	POST	Admin	Hot-reload hooks and configuration
`/.well-known/oauth-authorization-server`	GET	None	OAuth 2.0 discovery (RFC 8414)

Health check

GET /health

{
  "status": "healthy",
  "version": "2.0.265",
  "timestamp": "2026-04-02T10:30:00.000Z",
  "components": {
    "redis": { "status": "up", "latency_ms": 0.5 }
  }
}

Tool discovery

AI clients discover available tools automatically via the MCP tools/list method. Only services with configured credentials appear. The tool list updates dynamically when services are connected or disconnected.