Control Tool Access Per Key

A caller API key's allowed_tools decides which MCP tools that key can discover and call. The same field governs both directions: tools/list returns only the tools the key allows, and tools/call rejects any tool the key does not allow before AISIX contacts the upstream server.

Tools are named in the aggregated <server>__<tool> form, where <server> is the registered MCP server's display_name. A key with no allowed_tools — omitted, null, or an empty list — can call no MCP tools. Access is granted explicitly.

Matching Rules

Each allowed_tools entry is matched as a single-* glob 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 the narrowest access that fits the caller. A <server>__* grant is scoped to exactly that server: github__* does not match slack__post, and it does not match a different server whose name merely shares the prefix, such as githubenterprise__create_issue.

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"]
  }'

This key can call every tool on the github server plus the single runbooks__search tool, and nothing else.

Advanced matching

Because entries are single-* globs, * can appear anywhere, not only as a trailing <server>__*. For example, *__search grants a tool named search on every registered server. Prefer per-server (<server>__*) or exact grants unless you specifically want a cross-server pattern.

Update a Key's Tool Access

Updates replace the 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"]
  }'

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 the tools from every enabled server, then filters the list to the ones the caller's key allows. The client sees only permitted tools.

When the client calls a tool, AISIX re-checks the key against allowed_tools. 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. A caller can therefore neither discover nor invoke tools outside its grant.

Manage Tool Access on AISIX Cloud

On AISIX Cloud, you set tool access from the caller API key form in the dashboard instead of the Admin API:

• All MCP tools grants *.
• A checkbox for each MCP server exposed to the key's environment grants that server's <server>__*.
• An advanced field accepts exact tool names for fine-grained grants.

The stored grant maps back to these controls when you edit the key, so a hand-written exact grant is preserved. See AISIX Cloud.

Next Steps

• Upstream authentication — configure how AISIX authenticates to each server.
• MCP Gateway Overview — register a server and connect a client end to end.