# 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[​](#prerequisites "Direct link to 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](https://docs.api7.ai/ai-gateway/getting-started/aisix-cloud-quickstart.md). To request AISIX Cloud access, [contact API7](https://api7.ai/contact).
* For an open-source AISIX gateway, a caller API key and registered MCP server in `resources.yaml`. [Set Up MCP Gateway](https://docs.api7.ai/ai-gateway/mcp-gateway/setup.md) provides a working configuration and the validation and reload workflow.
* [cURL](https://curl.se/) and [jq](https://jqlang.org/) for the control-plane examples.

## How Tool Access Works[​](#how-tool-access-works "Direct link to 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](https://docs.api7.ai/ai-gateway/mcp-gateway/access-policies.md). 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:

| 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 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](https://docs.api7.ai/ai-gateway/mcp-gateway/access-policies.md) 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 "Direct link to Configure Tool Access")

Configure tool access using the management path for your deployment.

* AISIX Enterprise or Cloud
* AISIX OSS

- Dashboard
- Admin API

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](https://static.api7.ai/uploads/2026/11/17/0hJFhN5D_mcp-tool-grant.webp)

4. Select **Save changes**. Use **Show effective MCP permissions** or [verify tool access through the gateway](https://docs.api7.ai/ai-gateway/mcp-gateway/setup.md#verify-mcp-tool-access-with-http).

![Effective MCP permissions showing the exact everything echo tool allowed by the caller key](https://static.api7.ai/uploads/2026/11/20/UsLoUHiI_mcp-grant-saved.webp)

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.

Use the Admin API to create a caller API key with tool access or update the tool grant on an existing key.

### Create a Key[​](#create-a-key "Direct link to Create a Key")

Export the control-plane URL, admin token, and environment ID:

```
# AISIX_CP includes /api and has no trailing slash

# The local AISIX Enterprise quickstart uses http://localhost:8080/api

export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"

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": [],

    "mcp_access": { "allow": ["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 layer allows every tool on the `github` server plus the single `runbooks__search` tool, and nothing else. In AISIX Enterprise and AISIX Cloud, the key still only reaches what the environment and team layers also allow.

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[​](#update-tool-access "Direct link to Update Tool Access")

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

```
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 '{

    "mcp_access": { "allow": ["github__create_issue"] }

  }'
```

This update replaces the previous block with one allowing `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, send `"mcp_access": {"allow": []}`. The key keeps its model access and other settings but can no longer list or call any MCP tool, whatever the policy layers allow. Sending `"mcp_access": null` instead removes the key's layer, which is different: the key then follows the environment and team layers again.

Set `mcp_access` on the caller entry in `resources.yaml`:

resources.yaml (MCP access)

```
api_keys:

  - id: ad88beea-4db8-41ec-b817-3a33b22dfda8

    display_name: mcp-caller

    key_hash: ${MCP_CALLER_KEY_SHA256}

    allowed_models: []

    mcp_access:

      allow:

        - github__*

        - runbooks__search
```

Set `MCP_CALLER_KEY_SHA256` to the SHA-256 digest of the caller key in the gateway process environment. This caller can use every tool registered under `github` and only the `search` tool registered under `runbooks`. Other caller settings, including model and A2A access, remain on the same entry.

This example configures no `mcp_policies`, so the key's own block is its only access layer. A caller entry without `mcp_access` therefore has no MCP tool access.

To change the grant, edit the complete block, validate `resources.yaml`, and reload the gateway. Set `allow: []` to revoke all MCP tool access while retaining the key's other permissions. See [Set Up MCP Gateway](https://docs.api7.ai/ai-gateway/mcp-gateway/setup.md?product=oss#register-the-server-and-grant-a-tool) for the validation and reload commands.

## How Enforcement Works[​](#how-enforcement-works "Direct link to 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](https://docs.api7.ai/ai-gateway/mcp-gateway/overview.md#per-server-endpoints). 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[​](#next-steps "Direct link to 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](https://docs.api7.ai/ai-gateway/mcp-gateway/traffic-controls.md): apply request and concurrency limits, and configure budgets for MCP tool calls.
* [Guardrails](https://docs.api7.ai/ai-gateway/mcp-gateway/guardrails.md): inspect MCP tool arguments and results.
* [Caller API Keys](https://docs.api7.ai/ai-gateway/traffic-controls/caller-api-keys.md): review the shared key settings that also govern model and A2A traffic.
