MCP access

ApiGo provides two sets of MCP capabilities:

Entry	Address	Authentication	Audience
App MCP	`/mcp/{appCode}`	`X-AppKey` or `Authorization: Bearer <token>`	External AI clients calling published APIs
Admin MCP	`/api/box/mcp/{agentCode}`	`X-Agent-Key`	AI agents managing platform resources and APIs

Both use JSON-RPC 2.0 with the MCP protocol version 2025-06-18, but the tool sources, authentication and permission models differ.

App MCP

Prerequisites

For an API to appear in the App MCP tool list, all of the following must be satisfied:

The API's release protocol includes MCP;
The API is released to the prod environment and is live;
The API authentication method is app_key;
The calling credential has obtained access to the API (API-level authorization, or the credential has project-level scope);
MCP is enabled for the credential and the credential is not disabled.

When creating or editing an API, the MCP release protocol can only be selected when the authentication method is app_key; switching to another authentication method automatically removes MCP. MCP reuses REST's app_key authentication and does not require X-Sign.

Client configuration

Copy the configuration from Account Center → App Credentials → MCP configuration:

{
  "mcpServers": {
    "ApiGo-MCP": {
      "type": "http",
      "url": "https://www.apigo.cn/mcp/{appCode}",
      "headers": {
        "X-AppKey": "{AppKey}"
      }
    }
  }
}

When using OAuth2 client credentials, replace X-AppKey in headers with Authorization: "Authorization": "Bearer <access_token>".

For private deployments, replace the domain with the actual gateway address. The server only accepts POST:

GET requests return HTTP 405; a standalone SSE channel is not supported;
OPTIONS preflight requests are allowed;
Clients can specify the response form with Accept: application/json or Accept: text/event-stream;
The request body limit is 1 MiB and the response body limit is 4 MiB.

Authentication rules

The gateway first resolves the app from Authorization: Bearer <access_token> (OAuth2 client credentials) and falls back to X-AppKey when no token is present, then validates in order:

The app exists and is enabled;
The app has mcpEnabled = 1;
The {appCode} in the path matches the app's AppCode;
The source IP is in the app's IP whitelist (when a whitelist is configured).

With Bearer, the token comes from /oauth2/token using client_credentials; the app identity is taken from the AppKey inside the token, so X-AppKey is no longer needed. Authorization is a sensitive header and is not forwarded to the target API. See OAuth2 client credentials authentication for the exchange flow.

Enterprise IdP JWT is not available yet

The MCP entry point currently recognizes only platform OAuth2 tokens and X-AppKey. JWTs issued by an enterprise IdP cannot yet be used with /mcp/{appCode}; phase 2 will dispatch by the token's iss and add RFC 9728 / RFC 8707 support. APIs that also need MCP should keep app_key or oauth2 authentication.

If any validation fails, a JSON-RPC error is returned, the HTTP status remains 200, and error.data.code carries the business error code (for example, 40020 means MCP is not enabled).

Protocol interactions

initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  }
}

The response contains the protocol version, server information and tool capabilities:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": {
      "name": "{appCode}",
      "title": "{app name}",
      "version": "v1"
    },
    "capabilities": {
      "tools": { "listChanged": false }
    }
  }
}

notifications/initialized returns HTTP 202 with no response body.

tools/list

Returns all tools accessible to the current credential, without pagination:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Each tool contains a name, a description and a JSON Schema input definition. The parameter schema is generated from the API's request parameters; required parameters go into required and default values are written into default.

Tool name rules:

The MCP tool name configured on the API takes precedence (this field is not exposed in the current UI);
When not configured, the name is generated from the API path: non-alphanumeric characters are replaced with underscores, consecutive underscores are merged, and leading and trailing underscores are removed;
If the name starts with a digit, the api_ prefix is added;
Names longer than 64 characters are truncated;
On a name collision within the same credential, the name falls back to api_{apiId}.

tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "user_list",
    "arguments": {
      "pageNum": 1,
      "pageSize": 20
    }
  }
}

The calling process:

Look up the target API in reverse by tool name;
Validate the parameters: undeclared parameters raise Unknown argument, and missing required parameters raise Missing required argument;
Convert arguments into the header, query, path and body of the target request according to parameter location;
The gateway rewrites the request into a real request for the target API, which then continues through filters such as logging, WAF, flow control, circuit breaking, caching and subscription quota;
The target API response is wrapped as a JSON-RPC result, with the response body placed in result.content[0].text.

When tools/call is invoked:

The API's own authentication is skipped; identity is determined by the X-AppKey at the MCP entry;
Sensitive headers passed by the client, such as Authorization, Cookie, X-AppKey and signature headers, are not forwarded to the target API;
Logs record the MCP source and can be filtered in API logs;
API-level credentials remain bound by the subscription's validity period and daily call volume; exceeding the limit returns 40023;
Project-level credentials bypass API-level authentication directly but are still subject to flow control, circuit breaking, IP rules and WAF.

Error codes

JSON-RPC code	Meaning	Common cause
`-32700`	Parse error	The request body is not valid JSON
`-32600`	Invalid Request	Missing `jsonrpc`/`method`, the path is not `/mcp/{appCode}`, or the request body is too large
`-32601`	Method not found	Unsupported method
`-32602`	Invalid params	Unknown tool, missing parameters, undeclared parameters, or header parameters containing CR/LF
`-32603`	Internal error	Internal service exception
`-32001`	Auth error	The app does not exist, is disabled, has MCP not enabled, has a mismatched AppCode, or has an IP outside the whitelist

Business error codes are returned through error.data.code, for example 40020 (MCP not enabled), 40021 (subscription frozen or invalid) and 40023 (daily quota exceeded).

FAQ

Symptom	What to check
Initialization succeeds but the tool list is empty	The API has no MCP release, is not live in prod, does not use app_key authentication, or the credential is not authorized
Message that MCP is not enabled	Check "Enable MCP" in the app credential editor
Message that the AppCode does not match	The appCode in the client URL does not match the app that owns the AppKey
Tool call returns a parameter error	Check parameter names and required fields against the inputSchema returned by `tools/list`
Tool call returns 40021	Check whether the subscription is frozen, expired or unsubscribed
405 returned	The client uses GET or a standalone SSE channel; switch to POST

Admin MCP

Admin MCP is designed for AI agents to query and manage ApiGo resources.

Integration

Create an agent in Account Center → MCP, choose the agent type and bind tools;
After saving, you receive an Agent Key starting with ak_; the plaintext is shown only once;
Client request:

POST /api/box/mcp/{agentCode}
X-Agent-Key: {AgentKey}
Content-Type: application/json

Authentication rules:

The agent must exist and be enabled;
The Agent Key is SHA-256 hashed and compared with the hash stored in the database;
The agent creator must still be a valid user and have access to the project the agent belongs to;
The tool list is filtered by both the tools bound to the agent and the creator's admin-side permissions;
The project context comes from the project the agent belongs to, and all operations are subject to project isolation.

initialize, tools/list and tools/call behave the same as in App MCP; GET requests return 405 (SSE not supported). Authentication failures return -32603 with a specific reason (missing API Key, agent not found, disabled, invalid Key, creator unavailable, etc.).

Tool catalog

Admin MCP currently provides 32 tools: 18 read-only tools and 14 write tools.

Read-only tools:

Category	Tools
Data sources	`datasource_list`, `datasource_detail`, `datasource_test`
APIs	`api_list`, `api_page`, `api_detail`, `api_versions`, `api_sql_parse`, `api_path_check`, `api_mock_case_draft`
Logs	`api_log_query`, `api_log_traffic_trend`
Groups	`group_list`
Metadata	`metadata_schemas`, `metadata_tables`, `metadata_columns`
Credentials	`credential_list`, `credential_detail`

Write tools:

Category	Tools
Data sources	`datasource_add`, `datasource_update`, `datasource_delete`
APIs	`api_sql_save`, `api_proxy_save`, `api_publish`, `api_offline`, `api_online`, `api_delete`, `api_destroy`
Credentials	`credential_create`, `credential_bind`
Groups	`group_create`
Debugging	`api_debug_invoke`

Write tools trigger a second confirmation in the AI assistant; api_debug_invoke is also treated as a write operation because it may cause business side effects.

Recommendations

Create separate agents for different purposes and bind tools with least privilege;
Grant production write operations to only the necessary agents;
Disable or recreate an agent immediately if its Agent Key leaks;
The project an agent belongs to determines the scope of operations; for cross-project needs, create separate agents.

App MCP​

Prerequisites​

Client configuration​

Authentication rules​

Protocol interactions​

initialize​

tools/list​

tools/call​

Error codes​

FAQ​

Admin MCP​

Integration​

Tool catalog​

Recommendations​

Related documentation​