List MCP Servers

GET /mcp_servers

List MCP Servers

List MCP servers in the authenticated organization. Stored bearer secrets are never included in read responses.

Parameters

Responses

• 200: OK

• data (array, required): MCP servers visible to the authenticated organization.

• data[].id (string, required): MCP server ID.

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

• data[].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.

• data[].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.

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

• data[].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.

• data[].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.

• data[].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>.

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

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

• data[].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.

• data[].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).

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

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

• data[].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.

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

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

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

• data[].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.

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

• data[].submitted_at (string, optional): Time of the most recent submission.

• data[].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.

• data[].reviewed_at (string, optional): Time of the current approval decision.

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

• data[].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.

• data[].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.

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

• data[].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.

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

• data[].pending_change.submitted_by (string, optional): User who proposed the change.

• data[].pending_change.submitted_at (string, optional): Time the change was proposed.

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

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

• 401: Missing or invalid bearer.

• 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.

cURL

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