Set MCP Access Policy

PUT /environments/{env_id}/mcp_policy

Interactive request editor loads with JavaScript.

Authorization

BearerAdminToken

AuthorizationBearer <token>

Organization-scoped admin token. Read operations require a valid token, and write operations require a token with write permission.

In: header

Path Parameters

env_id*string

Environment ID that scopes the request.

Formatuuid

Request Body

application/json

Body for creating or replacing an MCP access policy layer. The write replaces the whole policy; an omitted deny is treated as empty.

allow*array<string>

Namespaced server__tool patterns this layer allows (*, server__*, or an exact server__tool). Each entry may use letters, digits, ., _, -, and *; other characters are rejected. Send [] to leave the covered keys no MCP tool access, or ["*"] for a layer that only subtracts through deny.

deny?array<string>

Namespaced server__tool patterns removed from the effective grant of every caller API key the policy covers, matched the same way as allow. Deny always wins.

enabled?boolean

Whether the policy is applied. Send false to keep the policy configured but inactive.

Defaulttrue

Response Body

`application/json`

curl -X PUT "$AISIX_CP/environments/$ENV_ID/mcp_policy" \  -H "Authorization: Bearer $AISIX_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "allow": [      "string"    ]  }'

{
  "mcp_policy": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "scope": "env",
    "env_id": "3f917d0d-4dff-42f3-97c4-6a5455dfe8c2",
    "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",
    "allow": [
      "string"
    ],
    "deny": [
      "string"
    ],
    "enabled": true,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

Request body or parameters failed validation.

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Missing or invalid bearer.

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "no org context"
  }
}

Authenticated request is not permitted.

{
  "error": {
    "code": "CUSTOM_KEY_DISABLED",
    "message": "custom API key values are disabled for this organization"
  }
}

Resource not found.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "provider key not found"
  }
}

Complete operation details and schema variants

PUT /environments/{env_id}/mcp_policy

Set MCP Access Policy

Create or replace the environment layer of the MCP tool ACL. allow: ["*"] covers every tool on every MCP server, including servers and tools registered later — choosing it is always an explicit decision, never a default. The layer narrows what keys can reach but never widens it: a key still only gets what its team layer and its own mcp_access block also allow.

Parameters

env_id (path, string, required): Environment ID that scopes the request.

Request body

Content type: application/json

allow (array, required): Namespaced server__tool patterns this layer allows (*, server__*, or an exact server__tool). Each entry may use letters, digits, ., _, -, and *; other characters are rejected. Send [] to leave the covered keys no MCP tool access, or ["*"] for a layer that only subtracts through deny.
deny (array, optional): Namespaced server__tool patterns removed from the effective grant of every caller API key the policy covers, matched the same way as allow. Deny always wins.
enabled (boolean, optional): Whether the policy is applied. Send false to keep the policy configured but inactive.

Responses

200: OK
mcp_policy (object, required): One layer of the MCP tool ACL: the environment policy (scope: env) or a team policy (scope: team). Layers intersect on allow and union on deny, together with the key's own mcp_access block.
mcp_policy.id (string, required): Policy ID.
mcp_policy.scope (string, required): Whether this policy is the environment layer or a team layer.
mcp_policy.env_id (string, optional): Environment the layer applies to. Present only for scope: env.
mcp_policy.team_id (string, optional): Team the layer applies to. Present only for scope: team.
mcp_policy.allow (array, required): Namespaced server__tool patterns this layer allows (*, server__*, or an exact server__tool). An empty list leaves the covered keys no MCP tool access; ["*"] narrows nothing, which is what a layer that only means to subtract tools sends alongside deny.
mcp_policy.deny (array, required): Namespaced server__tool patterns removed from the effective grant of every caller API key this layer covers. Deny always wins, on any layer.
mcp_policy.enabled (boolean, required): Whether the policy is applied. A disabled policy is kept but ignored.
mcp_policy.created_at (string, required): Time when the policy was created.
mcp_policy.updated_at (string, required): Time when the policy was last updated.
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 PUT /environments/{env_id}/mcp_policy, response 400 above.
403: Authenticated request is not permitted. Response fields (application/json): identical to PUT /environments/{env_id}/mcp_policy, response 400 above.
404: Resource not found. Response fields (application/json): identical to PUT /environments/{env_id}/mcp_policy, response 400 above.

cURL

curl -X PUT '$AISIX_CP/environments/{env_id}/mcp_policy' -H 'Authorization: Bearer $AISIX_TOKEN'

Set MCP Access Policy

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`