Get MCP Server by ID

GET /mcp_servers/{mcp_server_id}

Get MCP Server by ID

Get an MCP server. Stored bearer secrets are never returned.

Parameters

• mcp_server_id (path, string, required): MCP server ID.

Responses

• 200: OK
• mcp_server (object, required): An MCP tool source registered at the organization level and exposed to the environments listed in allowed_environments: either an upstream MCP (Model Context Protocol) server (type: mcp), or a REST API described by an OpenAPI document whose operations the gateway exposes as MCP tools (type: openapi). The secret (bearer token, API key, or OAuth client secret depending on auth_type) is write-only and never appears in this view.

A server reaches gateways only while approval_status is approved. Until then it exists solely as a registry entry: gateway clients cannot discover or call it.

• mcp_server.id (string, required): MCP server ID.

• mcp_server.org_id (string, required): Organization ID that owns this MCP server.

• mcp_server.name (string, required): Organization-unique name used as the tool namespace prefix. Tool names use the <name>__<tool> format, so names may contain letters, digits, _, ., and -, but cannot contain the reserved __ separator or start or end with a separator character. Names are limited to 56 characters so composed tool names stay within the MCP 128-character limit.

• mcp_server.type (string, required): What backs this server: a real upstream MCP server (mcp), or a REST API described by an OpenAPI document whose operations become the server's tools (openapi). Fixed at creation.

• mcp_server.url (string, required): Upstream MCP server URL (type: mcp), or the REST API base URL generated tool calls are issued against (type: openapi).

• mcp_server.spec_url (string, optional): Where the OpenAPI document was fetched from at write time (type: openapi servers created via spec_url only; empty for pasted documents). Provenance only — the data plane never re-fetches it.

• mcp_server.api_key_header (string, optional): Header name the API key is sent under for type: openapi servers with auth_type: api_key. Empty means the default x-api-key.

• mcp_server.tool_names (array, optional): The MCP tool names generated from the stored OpenAPI document (type: openapi only), validated collision-free at write time. Exposed to clients as <name>__<tool>.

• mcp_server.spec (object, optional): The stored, normalized OpenAPI document (type: openapi only). Returned on single-server reads; omitted from list responses.

• mcp_server.transport (string, required): MCP transport used to reach the upstream server.

• mcp_server.protocol_version (string, optional): MCP protocol revision the gateway uses when connecting to this server. When unset, the gateway opens the session with the initialize handshake, which negotiates among the pre-2026 protocol revisions — the right choice for most servers, including 2026-07-28 servers that keep backward compatibility. Set 2026-07-28 for a server that requires the stateless MCP 2026-07-28 revision (handshake-free server/discover startup); the connection fails rather than silently downgrading when the server does not support the configured revision. Only valid when type is mcp.

• mcp_server.auth_type (string, required): How AISIX authenticates to the upstream server. none = no credential; bearer = a bearer token supplied as secret; api_key = an API key supplied as secret and sent as the x-api-key header (overridable via api_key_header on type: openapi servers); oauth2 = OAuth 2.0 client credentials, where secret is the client secret and AISIX mints its own access token from client_id + token_url (+ optional scopes).

• mcp_server.client_id (string, optional): OAuth client identifier for the client credentials grant. Present only when auth_type is oauth2.

• mcp_server.token_url (string, optional): OAuth token endpoint where the client credentials are exchanged for an access token. Present only when auth_type is oauth2.

• mcp_server.scopes (array, optional): OAuth scopes requested in the token exchange (joined with spaces into the scope parameter). Present only when auth_type is oauth2 and scopes were configured.

• mcp_server.timeout_ms (integer, optional): Per-request timeout in milliseconds. AISIX applies its default when this value is unset.

• mcp_server.enabled (boolean, required): Whether the server is dispatched to the data plane.

• mcp_server.allowed_environments (array, required): Environment UUIDs this server is projected to. Empty array = projected to no environment.

• mcp_server.approval_status (string, required): Where the server stands in the review workflow. pending_review = submitted and waiting for a decision; approved = published to allowed_environments and reachable by gateway clients; rejected = refused, or an approval that was revoked. Patching an approved server through PATCH /mcp_servers/{id} keeps it approved — that caller may approve servers, so the edit publishes directly. PATCH /mcp_server_submissions/{id} revises a server that is not published yet and leaves it pending; against an approved server it stages the change in pending_change and leaves this status untouched, so the server keeps serving while the proposal waits.

• mcp_server.submitted_by (string, optional): User who last submitted this server for review. Absent when the submission came from an admin token.

• mcp_server.submitted_at (string, optional): Time of the most recent submission.

• mcp_server.reviewed_by (string, optional): User who made the current approval decision. Absent when the decision came from an admin token, or when no decision has been made yet.

• mcp_server.reviewed_at (string, optional): Time of the current approval decision.

• mcp_server.review_notes (string, optional): Reviewer's note left with the current decision.

• mcp_server.pending_change (object, optional): A change proposed against this server and waiting for review, submitted through PATCH /mcp_server_submissions/{mcp_server_id}. Absent when nothing is waiting.

Every other field on this server keeps describing the configuration that is projected and serving: a proposal changes nothing until it is approved. POST /mcp_servers/{id}/approve applies it, POST /mcp_servers/{id}/reject discards it, and neither takes the server off the gateways.

• mcp_server.pending_change.changes (object, required): The fields the proposal would change, in the shape of an update request. A proposed credential is never echoed here — see secret_set.

• mcp_server.pending_change.spec_url (string, optional): Fetch provenance of a proposed replacement OpenAPI document, when the proposal fetched one.

• mcp_server.pending_change.tool_names (array, optional): The tool surface a proposed replacement OpenAPI document would generate, so a reviewer sees what the tools become before approving it.

• mcp_server.pending_change.secret_set (boolean, optional): True when the proposal rotates the upstream credential. The value itself is stored encrypted and never returned.

• mcp_server.pending_change.submitted_by (string, optional): User who proposed the change.

• mcp_server.pending_change.submitted_at (string, optional): Time the change was proposed.

• mcp_server.created_at (string, required): Time when the MCP server was created.

• mcp_server.updated_at (string, required): Time when the MCP server was last updated.

• warnings (array, optional): Present on save and approval operations when some data plane nodes in the environments this server is exposed to run a gateway version that will not execute part of the saved configuration. Never present on reads.

• warnings[].code (string, required): How affected nodes treat the saved resource. field_ignored: the resource stays in service on those nodes but the named field has no effect there — beware when the field is restrictive, since the restriction is silently not enforced. row_rejected: those nodes refuse the whole resource, so it stops serving there entirely (or, if a previously accepted version exists, they keep serving the old values).

• warnings[].field (string, required): Dot-separated path of the field that triggered the warning, as delivered to gateway nodes.

• warnings[].min_dp_version (string, required): Oldest gateway version that fully executes the field. The literal value unreleased means no released gateway version executes it yet.

• warnings[].affected_dp_count (integer, required): Number of currently registered nodes in the environment running an older gateway version than min_dp_version.

• warnings[].affected_dp_versions (array, required): Distinct gateway versions reported by the affected nodes, capped at five entries. Nodes that report no version appear as unknown.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to GET /mcp_servers/{mcp_server_id}, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to GET /mcp_servers/{mcp_server_id}, response 400 above.

cURL

curl -X GET '$AISIX_CP/mcp_servers/{mcp_server_id}' -H 'Authorization: Bearer $AISIX_TOKEN'