Submit MCP Server for Review

POST /mcp_server_submissions

Submit MCP Server for Review

Proposes an upstream MCP server without publishing it. The server is registered with approval_status set to pending_review and is not projected to any environment, so it cannot be discovered or called until a reviewer approves it.

This is the entry point for roles that may propose servers but not publish them. Callers who hold write access on MCP servers can register a server directly with POST /mcp_servers, which creates it already approved.

Parameters

Request body

Content type: application/json

• name (string, required): 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.

• type (string, optional): What backs this server. mcp (the default): a real upstream MCP server reached at url. openapi: a REST API whose OpenAPI 3.x document — provided via exactly one of spec_content and spec_url — is turned into MCP tools, with url as the API base URL. Fixed at creation.

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

• spec_content (string, optional): The OpenAPI 3.x document itself, as JSON or YAML text (type: openapi only; at most 1 MiB). Validated, normalized to JSON, and stored at write time — clear errors are returned for an unparseable document, Swagger 2.0, zero tool-generatable operations, and operationIds that collide after tool-name sanitization.

• spec_url (string, optional): URL of the OpenAPI document (type: openapi only), fetched server-side ONCE at write time and stored — the data plane never re-fetches it, so the tool set cannot drift with the remote document. http(s) only; hosts resolving to non-public addresses are refused unless the deployment sets AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS=true (paste the document via spec_content otherwise).

• api_key_header (string, optional): Header name the API key is sent under (type: openapi with auth_type: api_key only). Defaults to x-api-key when omitted.

• 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. When omitted or null, 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.

• auth_type (string, optional): Authentication mode used when AISIX connects to the upstream server. Defaults to none when omitted.

• secret (string, optional): The credential — a bearer token, an API key, or an OAuth client secret depending on auth_type; write-only (envelope-encrypted on the server, never returned). Required for bearer / api_key / oauth2; must be absent/empty when auth_type is none.

• client_id (string, optional): OAuth client identifier. Required when auth_type is oauth2; must be absent/empty otherwise.

• token_url (string, optional): OAuth token endpoint URL where the client credentials are exchanged for an access token. Required when auth_type is oauth2; must be absent/empty otherwise.

• scopes (array, optional): Optional OAuth scopes (only with auth_type oauth2). Each entry is a single scope token — printable ASCII, no spaces, quotes, backslashes, commas, or braces.

• 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): Environments this server is exposed to. Empty or null values expose it to no environment.

Responses

• 201: Created
• 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 POST /mcp_server_submissions, response 400 above.

• 403: Authenticated request is not permitted. Response fields (application/json): identical to POST /mcp_server_submissions, response 400 above.

• 409: Request conflicts with current resource state. Response fields (application/json): identical to POST /mcp_server_submissions, response 400 above.

cURL

curl -X POST '$AISIX_CP/mcp_server_submissions' -H 'Authorization: Bearer $AISIX_TOKEN'