Update MCP Server

PATCH /mcp_servers/{mcp_server_id}

Update MCP Server

Update selected MCP server fields. A new secret rotates a bearer credential. This caller holds the permission that approves servers, so an approved server keeps serving across the patch and the new configuration is published immediately; the edit is recorded as its review. Taking a live server off the gateways is an explicit POST /mcp_servers/{id}/reject.

Parameters

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

Request body

Content type: application/json

• name (string, optional): Organization-unique name used as the tool namespace prefix. Names may contain letters, digits, _, ., and -, but cannot contain the reserved __ separator or start or end with a separator character.

• url (string, optional): Upstream MCP server URL (type: mcp), or the REST API base URL (type: openapi).

• spec_content (string, optional): Replacement OpenAPI 3.x document as JSON or YAML text (servers of type: openapi only — the type itself is fixed at creation). Re-validated and re-normalized exactly like on create; provide at most one of spec_content and spec_url.

• spec_url (string, optional): URL to fetch a replacement OpenAPI document from, once, server-side (servers of type: openapi only). Same validation and non-public-address guard as on create.

• api_key_header (string, optional): Header name the API key is sent under (type: openapi with effective auth_type: api_key only). An empty string resets to the default x-api-key.

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

• protocol_version (string, optional): MCP protocol revision the gateway uses when connecting to this server (servers of type: mcp only). 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. null clears the pin, returning the server to the initialize handshake that negotiates among the pre-2026 revisions.

• auth_type (string, optional): How AISIX authenticates to the upstream server.

• secret (string, optional): New credential — bearer token, API key, or OAuth client secret depending on the effective auth_type; write-only. Omitting it keeps the stored credential ONLY while the auth_type is unchanged: changing the auth_type to any credential-bearing type requires a fresh non-blank secret (the stored value is a different kind of credential). When the auth_type resolves to none, the stored credential is cleared.

• client_id (string, optional): OAuth client identifier. Required (present or already stored) when the effective auth_type is oauth2; cleared automatically when the auth_type moves away from oauth2.

• token_url (string, optional): OAuth token endpoint URL. Required (present or already stored) when the effective auth_type is oauth2; cleared automatically when the auth_type moves away from oauth2.

• scopes (array, optional): OAuth scopes (only meaningful with auth_type oauth2). Replaces the stored list when present; cleared automatically when the auth_type moves away from oauth2.

• timeout_ms (integer, optional): Per-request timeout in milliseconds.

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

• allowed_environments (array, optional): Replacement list of environments this server is exposed to.

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 PATCH /mcp_servers/{mcp_server_id}, response 400 above.

• 403: Authenticated request is not permitted. Response fields (application/json): identical to PATCH /mcp_servers/{mcp_server_id}, response 400 above.

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

• 409: Request conflicts with current resource state. Response fields (application/json): identical to PATCH /mcp_servers/{mcp_server_id}, response 400 above.

cURL

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