MCP Server Management

Use the Management API to manage MCP Servers and MCP Server Clients (OAuth clients registered for a specific MCP Server). All endpoints require a Management Key.

Authentication: Send your Project ID and Management Key as a bearer token:

Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>

MCP Server Endpoints

Create MCP Server

Endpoint: POST /v1/mgmt/mcp/server/create

Create a new MCP Server. The response returns the created server object.

Request body:

Identity: name, description, tags, logo
Access: audienceWhitelist, approvedScopes (see Approved scopes below), approvedCallbackUrls
Registration & consent: dynamicRegistration (DCR/CIMD and flow), skipConsentScreen, consentFlowId, consentFlowHostingURL
Session & CIMD: sessionSettings, cimdSettings

Approved scopes

approvedScopes is a single list of scopes that clients can request for this MCP Server. Each scope has:

name — Scope identifier (e.g. mcp:test, mcp:google.read).
description — Shown on consent screens.
optional — (Optional) If true, the client may omit this scope; if false or omitted, it can be required.
values — (Optional) If present, this scope is a connection scope: it grants access to the given Connections (resource URLs or connection identifiers). If values is omitted, the scope has no connection associated—it is considered a normal permission scope.

MCP server scopes

Example: scopes with no connection

"approvedScopes": [
  { "name": "mcp:test", "description": "Test Scope", "optional": true },
  { "name": "mcp:tools:write", "description": "Write access to tools", "optional": false }
]

Example: scopes with and without connections

"approvedScopes": [
  { "name": "mcp:test", "description": "Test Scope", "optional": true },
  {
    "name": "mcp:google.read",
    "description": "Read from Google Calendar",
    "values": ["https://api.googles.com/readonly"]
  }
]

Create example (full request)

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/create" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Server from API",
    "description": "Test description",
    "audienceWhitelist": ["https://app.example.com/api"],
    "dynamicRegistration": {
      "enabled": true,
      "flowId": "sign-up-or-in"
    },
    "approvedScopes": [
      { "name": "mcp:test", "description": "Test Scope", "optional": true },
      {
        "name": "mcp:google.read",
        "description": "Read from Google Calendar",
        "values": ["https://api.googles.com/readonly"]
      }
    ],
    "cimdSettings": {
      "enabled": true,
      "domainPolicies": {
        "policies": [
          { "domainPattern": "*", "enabled": true }
        ]
      }
    }
  }'

Load MCP Server

Endpoint: POST /v1/mgmt/mcp/server/load

Load a single MCP Server by ID. The response includes the full server object.

Request body:

Required: id

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/load" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "<MCP_SERVER_ID>"}'

Load All MCP Servers

Endpoint: POST /v1/mgmt/mcp/servers/all

Load all MCP Servers in the project. The response returns a servers array.

Request body:

Optional: Pagination and filter fields (see API reference). Can be {}.

curl -X POST "https://api.descope.com/v1/mgmt/mcp/servers/all" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

Update MCP Server

Endpoint: POST /v1/mgmt/mcp/server/update

Update an existing MCP Server. The response returns the updated server object.

Request body:

Required: server — Full MCP Server object including id; include all fields you want to keep (same shape as create, including approvedScopes).

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/update" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "id": "<MCP_SERVER_ID>",
      "name": "Test Server (Updated)",
      "description": "Updated description",
      "audienceWhitelist": ["https://app.example.com/api"],
      "dynamicRegistration": { "enabled": true, "flowId": "sign-up-or-in" },
      "approvedScopes": [
        { "name": "mcp:test", "description": "Test Scope", "optional": true },
        { "name": "mcp:tools:write", "description": "Write access", "optional": false },
        {
          "name": "mcp:google.read",
          "description": "Read from Google Calendar",
          "values": ["https://api.googles.com/readonly"]
        }
      ],
      "approvedCallbackUrls": ["https://myapp.example.com/callback"],
      "skipConsentScreen": false
    }
  }'

Delete MCP Server

Endpoint: POST /v1/mgmt/mcp/server/delete

Delete a single MCP Server.

Request body:

Required: id

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/delete" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "<MCP_SERVER_ID>"}'

Delete MCP Servers (bulk)

Endpoint: POST /v1/mgmt/mcp/servers/delete

Delete multiple MCP Servers by ID.

Request body:

Required: ids — Array of MCP Server IDs

curl -X POST "https://api.descope.com/v1/mgmt/mcp/servers/delete" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["<MCP_SERVER_ID_1>", "<MCP_SERVER_ID_2>"]}'

MCP Server Client Endpoints

MCP Server Clients are OAuth clients (agents or applications) registered for a specific MCP Server.

Create MCP Server Client

Endpoint: POST /v1/mgmt/mcp/server/client/create

Create a new MCP Server Client. The response returns id, clientId, and cleartext (client secret—store it securely; it is only returned once).

Request body:

Required: name, mcpServerId
Optional: approvedCallbackUrls, scopes, tags, logo

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/client/create" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "mcpServerId": "<MCP_SERVER_ID>",
    "approvedCallbackUrls": ["https://myapp.example.com/oauth/callback"],
    "scopes": ["mcp:tools:read", "mcp:tools:write"],
    "tags": ["agent", "support"]
  }'

Update MCP Server Client

Endpoint: POST /v1/mgmt/mcp/server/client/update

Update an existing MCP Server Client. The response returns the updated client object.

Request body:

Required: id, mcpServerId
Optional: name, approvedCallbackUrls, scopes, tags, logo

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/client/update" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<CLIENT_ID>",
    "mcpServerId": "<MCP_SERVER_ID>",
    "name": "Support Agent (Updated)",
    "approvedCallbackUrls": ["https://myapp.example.com/oauth/callback"],
    "scopes": ["mcp:tools:read", "mcp:tools:write", "mcp:admin"],
    "tags": ["agent", "support", "v2"]
  }'

Load MCP Server Client

Endpoint: POST /v1/mgmt/mcp/server/client/load

Load a single MCP Server Client by ID. The response returns the client object.

Request body:

Required: id, mcpServerId

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/client/load" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "<CLIENT_ID>", "mcpServerId": "<MCP_SERVER_ID>"}'

Search MCP Server Clients

Endpoint: POST /v1/mgmt/mcp/server/clients/search

Search MCP Server Clients for a given MCP Server. The response returns a clients array and total.

Request body:

Required: mcpServerId
Optional: page, limit, text, name, clientId, status, registrationMethod, tag, sort

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/clients/search" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "mcpServerId": "<MCP_SERVER_ID>",
    "page": 0,
    "limit": 20,
    "name": "Support",
    "status": "active"
  }'

Delete MCP Server Client

Endpoint: POST /v1/mgmt/mcp/server/client/delete

Delete a single MCP Server Client.

Request body:

Required: id, mcpServerId

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/client/delete" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "<CLIENT_ID>", "mcpServerId": "<MCP_SERVER_ID>"}'

Delete MCP Server Clients (bulk)

Endpoint: POST /v1/mgmt/mcp/server/clients/delete

Delete multiple MCP Server Clients by ID.

Request body:

Required: ids (array of client IDs), mcpServerId

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/clients/delete" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["<CLIENT_ID_1>", "<CLIENT_ID_2>"], "mcpServerId": "<MCP_SERVER_ID>"}'

Get MCP Server Client Secret

Endpoint: POST /v1/mgmt/mcp/server/client/secret

Retrieve the current client secret. The response returns cleartext (the secret).

Request body:

Required: id, mcpServerId

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/client/secret" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "<CLIENT_ID>", "mcpServerId": "<MCP_SERVER_ID>"}'

Rotate MCP Server Client Secret

Endpoint: POST /v1/mgmt/mcp/server/client/secret/rotate

Rotate a client's secret. The response returns the new cleartext secret (store it securely; it is only returned once).

Request body:

Required: id, mcpServerId

curl -X POST "https://api.descope.com/v1/mgmt/mcp/server/client/secret/rotate" \
  -H "Authorization: Bearer <PROJECT_ID>:<MANAGEMENT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "<CLIENT_ID>", "mcpServerId": "<MCP_SERVER_ID>"}'

Was this helpful?

Ask AI about this page

On this page