Create MCP API Proxy

Endpoint

POST /apiops/projects/{projectName}/apiProxies/mcp/{apiProxyName}/

Creates an API proxy of type MCP. See MCP Gateway for the concepts — Expose Tools vs Passthrough, protocol versions, and the inline-server model.

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Permission: API_MANAGEMENT × MANAGE.

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	MCP API proxy name. Overrides any name carried in the body.

Request Body

Field	Type	Required	Description
relativePath	string	Yes	Client-facing path the gateway listens on (for example `/mcp/support`)
description	string	No	Free-text description
routingMode	string	Yes	`TOOL_EXPOSE` or `PASSTHROUGH`. Unlike the AI proxy create endpoint, there is no implicit default — the same fail-closed contract Update MCP Routing uses
protocolVersion	string	No	MCP protocol version (`2024-11-05`, `2025-06-18`, `2026-07-28`); blank keeps the null-safe default

Full JSON Body Example (TOOL_EXPOSE)

{
  "relativePath": "/mcp/support",
  "description": "Exposes the support API as MCP tools",
  "routingMode": "TOOL_EXPOSE"
}

exposedTools isn't part of this create call — add tool definitions afterward with Update MCP Routing, the same "create first, route afterward" pattern Create AI API Proxy uses for aiRouting.

uyarı

This endpoint has no backendServers field, and PASSTHROUGH mode requires at least one inline backend server entry — sending "routingMode": "PASSTHROUGH" here always fails with HTTP 400 (mcpRouting.backendServersRequired). There is no name-based reference that can satisfy this requirement instead. To end up with a PASSTHROUGH proxy, create it with TOOL_EXPOSE first (an empty exposedTools list is valid), then switch it over in a single Update MCP Routing call that carries routingMode: "PASSTHROUGH" and backendServers together.

Two-Step PASSTHROUGH Setup

1. Create the proxy (POST /apiops/projects/{projectName}/apiProxies/mcp/{apiProxyName}/):

{
  "relativePath": "/mcp/github",
  "routingMode": "TOOL_EXPOSE"
}

2. Switch it to PASSTHROUGH with an inline backend server (PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/mcp-routing/):

{
  "routingMode": "PASSTHROUGH",
  "backendServers": [
    {
      "name": "github-mcp",
      "endpoint": "https://mcp.github.example.com/mcp",
      "transport": "HTTP_SSE",
      "authScheme": "BEARER",
      "bearerToken": "raw-token-in-transit-only"
    }
  ]
}

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": false,
    "detailList": []
  }
}

Creation does not deploy the proxy. Deploy it separately with POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/environments/{environmentName}/.

Error Responses

HTTP Code	Condition
400	`apiProxyName` is empty, request body is missing, `relativePath` is empty, `routingMode` is missing, an API proxy with the same name already exists in the project, or `routingMode` is `PASSTHROUGH` (this endpoint carries no `backendServers`, so the required-backend check always fails)
401	Token is missing or invalid
500	Unexpected server error

{
  "status": "FAIL",
  "message": "routingMode value can not be empty! Must be TOOL_EXPOSE or PASSTHROUGH."
}

Notes and Warnings

routingMode is required, with no default. This mirrors the routing-update endpoint's fail-closed contract — there's no implicit mode to fall back to.
Servers are configured inline, not by reference — there is no reference option. This create call has no backendServers field, so a PASSTHROUGH target can't be set in one step: create the proxy (with TOOL_EXPOSE), then add one or more inline MCP servers through Update MCP Routing's backendServers field, in the same call that switches routingMode to PASSTHROUGH.
Proxy-level settings apply the same as any other proxy type — CORS, cache, error templates, client route, trace and traffic-log settings.
Policies (including MCP Call (LLM) / MCP Call (Fixed) on other proxies) are attached the same way as for any other proxy, through POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/.

Endpoint​

Authentication​

Header​

Request​

Headers​

Path Parameters​

Request Body​

Full JSON Body Example (TOOL_EXPOSE)​

Two-Step PASSTHROUGH Setup​

Response​

Success Response (200 OK)​

Error Responses​

Notes and Warnings​

Related Documentation​