Get MCP Server by ID

GET /admin/v1/mcp_servers/{id}

Get MCP Server by ID

Get an upstream MCP server resource by ID.

Parameters

• id (path, string, required): MCP server resource ID, as assigned by the active resource source (a UUIDv5 derived from the entry name in file mode; the etcd key's ID segment otherwise).

Responses

• 200: OK
• id (string, required): Resource ID, as assigned by the active resource source.
• revision (integer, required): Monotonic resource revision: the etcd mod_revision of the entry, or the load generation in file mode.
• value (object, required): Stored upstream MCP server configuration.
• allOf variant 1
• value.api_key_header (string,null, optional): Header name the API key is sent under when type is openapi and auth_type is api_key. Defaults to x-api-key when unset. Ignored for type: mcp, whose API-key header is fixed.
• value.auth_type (object, optional): How the gateway authenticates to the upstream server. The credential is held by the gateway and is never forwarded from or exposed to the calling client.
• allOf variant 1
• oneOf variant 1: No authentication
• oneOf variant 2: Bearer token
• oneOf variant 3: API key
• oneOf variant 4: OAuth 2.0 client credentials
• value.client_id (string,null, optional): OAuth client identifier used for the OAuth 2.0 client credentials grant. Required when auth_type is oauth2; ignored otherwise.
• value.display_name (string, optional): Accepted as an alternative spelling of name. Provide the label under exactly one of the two names.
• value.enabled (boolean, optional): Whether this server is active. When false, its tools are not listed and cannot be called.
• value.forward_client_headers (array, optional): Inbound client headers forwarded to this server, as single-* glob patterns matched case-insensitively against the header name ("x-trace-*", "authorization"). Empty — the default — forwards nothing. Applies to both type: mcp and type: openapi, so a REST API exposed here as tools receives them on every tool call.

A header the caller sends more than once is forwarded with its first value only; the upstream receives one well-formed header rather than a list this gateway never interpreted. An HTTP/2 caller may split cookie across several header fields, and only the first of them is forwarded.

A header named here reaches the server whatever the gateway would otherwise do with it. Naming the credential slot auth_type would fill — authorization for bearer and oauth2, api_key_header for api_key — hands the server the caller's own credential in place of the gateway's, never both. That is what lets an internal server that already authorizes on the end user's Authorization keep doing so unchanged. A server that validates the aud claim will reject a token minted for the gateway.

A credential slot, and traceparent / tracestate, are forwarded only when a pattern names them exactly — a glob such as "*" or "x-*" is a statement about the operator's own headers, not consent to hand a third party the caller's credential or to graft the caller's trace onto that party's telemetry.

Headers whose forwarding would break the exchange rather than change who it comes from are never forwarded whatever the patterns say: host, the hop-by-hop headers that describe the caller's own connection, the gateway's x-aisix-* namespace, the headers describing a body this gateway re-serializes (content-type, content-length, accept), and the MCP session slots (mcp-session-id, mcp-protocol-version, last-event-id), which name the caller's session with this gateway and which an upstream MCP server refuses outright when they carry a foreign value.

• value.name (string, optional): Operator-facing label, unique within the gateway. It is used as the namespace prefix for this server's tools, which are exposed to clients as <name>__<tool>, so it must not contain the reserved separator __.
• value.protocol_version (object, optional): MCP protocol revision the gateway uses when connecting to this upstream server. When omitted, 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 used when type is mcp; ignored for type: openapi.
• allOf variant 1
• oneOf variant 1: MCP 2026-07-28
• value.scopes (array,null, optional): OAuth scopes to request. Joined with spaces into the scope parameter of the token request. Only used when auth_type is oauth2.
• value.secret (string,null, optional): Authentication credential for the upstream server. Its meaning follows auth_type: the bearer token when auth_type is bearer (sent as Authorization: Bearer <secret>), the API key when auth_type is api_key (sent as x-api-key: <secret>, or under api_key_header for type: openapi), or the OAuth client secret when auth_type is oauth2. Leave unset when auth_type is none.
• value.spec (object, optional): The OpenAPI 3.x document (as a JSON object) whose operations become this server's tools. Required when type is openapi; ignored otherwise.
• value.timeout_ms (integer,null, optional): Maximum time, in milliseconds, to wait for a single upstream operation (establishing the session, listing tools, or calling a tool). Must be at least 1 when set. When omitted, the gateway applies a built-in default.
• value.token_url (string,null, optional): OAuth token endpoint URL where the gateway exchanges the client credentials for an access token, such as https://auth.example.com/oauth/token. Required when auth_type is oauth2; ignored otherwise.
• value.transport (object, optional): Transport used to reach the upstream server. Streamable HTTP is the only supported transport.
• allOf variant 1
• oneOf variant 1: Streamable HTTP
• value.type (object, optional): What backs this server: a real upstream MCP server (mcp, the default), or a plain REST API described by an OpenAPI document (openapi) whose operations the gateway itself exposes as MCP tools.
• allOf variant 1
• oneOf variant 1: Upstream MCP server
• oneOf variant 2: REST API described by an OpenAPI document
• value.url (string, required): For type: mcp, the upstream server's MCP endpoint URL, reached over the Streamable HTTP transport, such as https://api.example.com/mcp. For type: openapi, the REST API's base URL that generated tool calls are issued against, such as https://erp.internal/api/v1.
• allOf variant 1
• allOf variant 2
• allOf variant 3
• allOf variant 4
• allOf variant 5
• anyOf variant 1: name
• anyOf variant 2: display_name
• 401: Missing or invalid admin key
• error_msg (string, required): Human-readable error message.
• 404: Resource not found Response fields (application/json): identical to GET /admin/v1/mcp_servers/{id}, response 401 above.
• 500: Configuration store operation failed Response fields (application/json): identical to GET /admin/v1/mcp_servers/{id}, response 401 above.

cURL

curl -X GET 'http://127.0.0.1:3001/admin/v1/mcp_servers/{id}'