MCP Gateway API

The MCP Gateway provides a unified HTTP interface for the Model Context Protocol. MCP clients can authenticate with OAuth, then list and call tools through one endpoint.

Key Concepts

Endpoint

POST https://clevername.net/api/hub/mcp/gateway

MCP protocol over HTTP

The gateway translates the MCP protocol (originally designed for stdio/SSE transport) into a standard HTTP request/response format. This lets any HTTP client interact with MCP servers without needing a persistent connection or MCP client library.

Authentication

MCP-capable IDEs should connect to https://clevername.net/api/hub/mcp/gatewayand follow the OAuth browser login flow automatically. Raw HTTP clients can call the same endpoint with an OAuth access token or a fallback cn-live-* gateway token.

Supported operations

Method	Description
tools/list	List all available tools from active MCP servers
tools/call	Execute a specific tool with provided arguments

Your own MCP servers (cx_ tools)

An agent can also call tools on an MCP server your organization connected, namedcx_<server>__<tool>. They appear in tools/list only after the server is shared with the organization and turned on for that agent. Every call is scanned like any other gateway call. Actions ask for human approval unless an admin trusts the server's read-only labels and the action is marked read-only (and doesn't look like it changes anything).

Endpoints (turning tools on or off needs an MFA-verified session or a personal gateway token):

POST /api/hub/mcp/connections/{id}/share {"org_id": "..."} # org admin GET /api/hub/ai-council/agents/{agent}/connected-tools # tools, states, metadata_verdict, stale, tool_cache_hash GET /api/hub/mcp/connections/{id} # one connection + metadata_verdicts per tool PUT /api/hub/mcp/connections/{id}/agents/{agent} {"tool_cache_hash": "...", "trust_read_only_labels": false, "overrides": {"delete_file": "off", "get_issue": "always_ask", "new_tool": "on"}} DELETE /api/hub/mcp/connections/{id}/agents/{agent} # turn the tool off for the agent

Send back the tool_cache_hash from the GET: if the server's tools changed in between, the PUT returns 409. Every listed action is included unless overridden off; actions the server added since the last save are only included with on.

Step-by-Step Guide

List available tools

Send a tools/list request to see all tools available from your active MCP servers:

POST /api/hub/mcp/gateway Authorization: Bearer <oauth_access_token_or_cn-live_token> { "method": "tools/list" }

The response includes each tool's name, description, and parameter schema. Tools are namespaced by their MCP server (e.g., github__create_issue).

tools/list response showing tool names, descriptions, and parameter schemas from multiple MCP servers

The tools/list response shows all available tools grouped by MCP server.

Call a tool

Execute a tool by sending a tools/call request with the tool name and arguments:

POST /api/hub/mcp/gateway Authorization: Bearer <oauth_access_token_or_cn-live_token> { "method": "tools/call", "params": { "name": "github__list_repos", "arguments": { "org": "my-company", "per_page": 10 } } }

Note

Tool names use double-underscore notation:{server}__{tool}. The server prefix identifies which MCP server handles the call.

Understand how the tool list is scoped

tools/list takes no filter parameters. The set you see is determined by the caller: a human token or OAuth session lists tools from all of your active MCP servers, while an agent-bound token lists only the tools assigned to that agent (or, once a governed session carries a guardrail-profile allowlist, only the tools that allowlist permits). Proxy clients with a tool allowlist are narrowed further.

Handle tool responses

Tool call responses follow the MCP result format with a content array. Each item has a type (usually “text”) and the result data. Error responses include an isError flag.

Gateway Tokens Authentication