Skip to main content
API7.ai Logo

Control Tool Access

For MCP traffic, the caller API key is the tool-access boundary. A key cannot list or call an MCP tool until access is granted explicitly.

Configure tool access when different clients should reach different upstream tools through the same gateway. This guide explains how AISIX names aggregated tools, how to create or update a key with tool access, and how enforcement behaves when a caller lists or calls tools.

Managing many keys?

Per-key allowlists are the narrowest control. Use Manage MCP Access with Policies to grant access at the environment or team level. Caller API keys can then inherit the shared grant, including tools registered later when all or a matching wildcard covers them.

How Tool Access Works​

Tool access is stored on the caller API key in allowed_tools. The value is a list of prefixed tool names or patterns. When the field is omitted, set to null, or set to an empty list, the key has no MCP tool access.

AISIX names each exposed tool in the <server>__<tool> form. The <server> segment is the registered MCP server's name; the <tool> segment is the upstream tool name. For example, github__create_issue calls the upstream create_issue tool on the registered github server.

Each entry in allowed_tools is matched against the prefixed tool name:

EntryGrantsExample
Exact nameOne specific tool.github__create_issue allows only that tool.
<server>__*Every tool on one registered server.github__* allows github__create_issue, github__list_repos, and any other github tool.
*Every tool on every registered server.* allows all current and future tools.

Choose exact names for the narrowest access. Use a per-server wildcard when a caller may use every tool on one server, and use * only for a key that may reach every current and future MCP tool.

Entries are single-asterisk globs, so the wildcard can appear outside the trailing per-server form. For example, *__search grants a tool named search on every registered server. Prefer per-server or exact grants unless you specifically need a cross-server pattern.

Create a Key with Tool Access​

The examples on this page use the AISIX Cloud Admin API. Use the control-plane URL, environment ID, and write-scoped admin token for your organization. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7. Then set:

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create the caller API key that the MCP client uses. This example grants every tool on one server plus one specific tool on another server:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "mcp-caller",
    "allowed_models": [],
    "allowed_tools": ["github__*", "runbooks__search"]
  }' > api_key.json

export API_KEY_ID=$(jq -r '.api_key.id' api_key.json)
export CALLER_KEY=$(jq -r '.plaintext' api_key.json)

❶ Use an empty model allowlist when the key is only for MCP traffic.

❷ This grant allows every tool on the github server plus the single runbooks__search tool, and nothing else.

The response returns the plaintext bearer in plaintext exactly once. Store it on the client side immediately; subsequent reads return only key metadata. The MCP client sends this value as Authorization: Bearer <plaintext> on gateway requests.

Update Tool Access for a Key​

Update the caller API key when its tool grant changes. The update is partial: only the fields you send are changed, and allowed_tools is replaced as a whole list:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_tools": ["github__create_issue"]
  }'

This update replaces the previous tool grant with github__create_issue only. The key's model access and other settings are untouched because the request does not include them.

To revoke all MCP tool access for a key, set allowed_tools to []. The key keeps its model access and other settings but can no longer list or call any MCP tool.

How Enforcement Works​

When an MCP client lists tools, AISIX aggregates tools from every enabled server, then filters the list by the caller's effective grant. AISIX resolves this grant from the caller API key and any applicable MCP access policies. The client sees only permitted tools.

When the client calls a tool, AISIX checks the effective grant again before contacting the upstream server. A tool the caller cannot access is rejected with a neutral MCP error and is never routed upstream. The rejection does not reveal whether the tool or server exists.

The same grant applies at a per-server endpoint. AISIX evaluates each tool in namespaced <server>__<tool> form, then normally presents permitted tools under their original names. For example, a grant for github__create_issue presents create_issue at /mcp/github but grants nothing at another server's endpoint.

AISIX Cloud Control Plane​

Tool access can also be configured from the control plane user interface instead of the API calls shown above. The same grant model applies: a caller API key can be scoped to individual tools, to every tool on a server, or to every MCP tool available in the environment. This workflow is available with both AISIX Cloud control-plane deployment options: On-Premises and Hybrid Cloud.

Next Steps​

You have now scoped which MCP tools each caller API key can list and call. Use these guides to add runtime controls or review the shared caller-key settings: