MCP Server Management

The Management API lets you create and manage MCP Servers, and the MCP Server Clients pre-registered for them, from code instead of the Console. This is useful when you create a server for each customer deployment, or keep MCP server configuration in CI.

This page covers what each endpoint is for and how to shape the request body. For every field and response, see the API reference.

Authentication

Every endpoint needs a Management Key. Send your Project ID and the key as a bearer token:

Authorization: Bearer __ProjectID__:<MANAGEMENT_KEY>

MCP Server Endpoints

The create body groups into a few kinds of settings, each matching a section of the MCP server settings in the Console:

• Identity: name, description, tags, logo
• Access: audienceWhitelist, approvedScopes, approvedCallbackUrls
• Registration and consent: dynamicRegistration, cimdSettings, skipConsentScreen, consentFlowId, consentFlowHostingURL
• Session: sessionSettings

Approved Scopes

approvedScopes is an object with three lists, one for each kind of scope a client can request:

• permissionsScopes: What the client can do on the MCP server, such as mcp:tools:write.
• attributesScopes: What the client can know about the user. See Attribute Scopes, for how these map to claims.
• connectionsScopes: Scopes that grant access to Connections, so the MCP server can fetch the user's third-party credentials. See MCP Server Scopes, for how these work in the Console.

Each scope in a list has a name, a description shown on the consent screen, optional to let the user decline it, and an optional values array. In connectionsScopes, values lists the Connection scopes the MCP scope grants.

"approvedScopes": {
  "permissionsScopes": [
    { "name": "mcp:tools:read", "description": "Read tools", "optional": false },
    { "name": "mcp:tools:write", "description": "Write tools", "optional": true }
  ],
  "connectionsScopes": [
    {
      "name": "mcp:calendar.read",
      "description": "Read your Google Calendar",
      "values": ["https://www.googleapis.com/auth/calendar.readonly"]
    }
  ]
}

Example: Create an MCP Server

curl -X POST "__BaseURL__/v1/mgmt/mcp/server/create" \
  -H "Authorization: Bearer __ProjectID__:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Calendar MCP Server",
    "description": "Calendar tools for agents",
    "audienceWhitelist": ["https://mcp.example.com/mcp"],
    "dynamicRegistration": { "enabled": true, "flowId": "sign-up-or-in" },
    "cimdSettings": {
      "enabled": true,
      "domainPolicies": { "policies": [{ "domainPattern": "*", "enabled": true }] }
    },
    "approvedScopes": {
      "permissionsScopes": [
        { "name": "mcp:tools:read", "description": "Read tools", "optional": false }
      ]
    }
  }'

The response returns the created server object, including the id you pass to the other endpoints.

MCP Server Client Endpoints

MCP Server Clients are OAuth clients, such as agents or applications, that you pre-register for one MCP Server. Every client endpoint takes the mcpServerId the client belongs to.

Creating a client and rotating its secret both return the secret as cleartext. Store it securely as soon as you get it.