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.

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 display_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:

Entry	Grants	Example
Exact name	One 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

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 "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_tools": ["github__*", "runbooks__search"]
  }'

❶ 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.

Update Tool Access for a Key

Update the caller API key when its tool grant changes. The Admin API PUT replaces the whole key resource, so include the existing key hash and any other fields you want to keep, along with the new allowed_tools:

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/YOUR_API_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_tools": ["github__create_issue"]
  }'

This update keeps the key MCP-only and replaces the previous tool grant with github__create_issue only. If the key also needs model access, keep its existing allowed_models values in the update.

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 to the tools the caller API key allows. The client sees only permitted tools.

When the client calls a tool, AISIX checks the key against allowed_tools again before contacting the upstream server. A tool the key does not allow is rejected with a neutral MCP error and is never routed upstream. The rejection does not reveal whether the tool or server exists.

Managed Control Plane

In a managed deployment, configure tool access from the control plane instead of sending these Admin API commands directly. 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 AISIX Cloud and AISIX Cloud On-Premises.

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:

Rate limits and budgets: apply request limits, concurrency limits, and budgets to MCP tool calls.
Guardrails: inspect MCP tool arguments and results.
Caller API Keys: review the shared key settings that also govern model and A2A traffic.

How Tool Access Works​

Create a Key with Tool Access​

Update Tool Access for a Key​

How Enforcement Works​

Managed Control Plane​

Next Steps​