Skip to main content
Version: 1.11.0

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.

Choose the narrowest exact, per-server, or global grant that fits the caller, then verify the effective tools the key can list and call.

Prerequisites​

Before starting, prepare the following:

  • For AISIX Enterprise or AISIX Cloud, an environment and a registered MCP server. Dashboard users need permission to create or update caller API keys. Admin API users need a write-scoped token from an identity with the same API-key permissions. For AISIX Enterprise, follow the AISIX Enterprise getting-started guide. To request AISIX Cloud access, contact API7.
  • For an open-source AISIX gateway, a caller API key and registered MCP server in resources.yaml. Set Up MCP Gateway provides a working configuration and the validation and reload workflow.
  • cURL and jq for the control-plane examples.

How Tool Access Works​

Tool access is stored on the caller API key in mcp_access, with an allow list and an optional deny list. This is the key's own ACL layer. In AISIX Enterprise and AISIX Cloud, it is intersected with environment and team MCP access policies. The key can narrow those layers but never widen them.

When the block is omitted the key adds no constraint of its own. That means it takes whatever the policy layers leave — and with no policy configured anywhere, no MCP tool access at all. Access is always granted explicitly.

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 allow 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 the caller may use every tool on one server. Use * with deny when the key should only subtract tools from broader policy layers. An empty allow list leaves the key with no MCP access.

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.

An entry can contain at most one *. The AISIX Cloud Admin API rejects an entry with two or more, such as *__*, with 400. A resources file does not check this, but the gateway never glob-matches such an entry, so in allow it grants nothing and in deny it never fires.

deny uses the same patterns and always wins: a tool matched there is unavailable however the key or any policy layer allows it.

Managing many keys?

A per-key block is the narrowest control. In AISIX Enterprise and AISIX Cloud, use Manage MCP Access with Policies to grant access at the environment or team level. Keys that add no block of their own then follow the shared layer, including tools registered later when a matching wildcard covers them.

Configure Tool Access​

Configure tool access using the management path for your deployment.

  1. Enter the environment, open API keys, and select Edit on the caller key.
  2. Select This key limits its own MCP tools.
  3. To grant one tool, clear All MCP tools and the server checkboxes. Expand Advanced — exact tool names and enter the namespaced tool, such as everything__echo.
Caller key limited to the exact everything echo tool
  1. Select Save changes. Use Show effective MCP permissions or verify tool access through the gateway.
Effective MCP permissions showing the exact everything echo tool allowed by the caller key

For a broader grant, select a server to allow all its tools or select All MCP tools. Environment and team policies still constrain the effective result.

How Enforcement Works​

When an MCP client lists tools, AISIX aggregates tools from every enabled server. It then filters the list by the intersection of every access layer that applies to the key. 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.

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 and concurrency limits, and configure budgets for 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.