MCP agent keys

Overview

Agent keys are scoped API keys that AI agents use to authenticate with the MCP Gateway. Each key controls which tools the agent can call, how fast it can call them and when the key expires.

You'll find them at AI Gateway > Agent Control > Agent keys.

Agent keys are prefixed with sk-mcp- and work as Bearer tokens. Your agent includes the key in the Authorization header when connecting to POST /v1/mcp.

Key list

The main view lists all agent keys for your organization. Each row shows:

• Name: The display name you gave the key.
• Status chip: "Active", "Revoked", "Expired" or "Inactive". Keys in monitor only mode also show a "Monitor only" chip, and a line under the name saying since when and who set it.
• Key prefix: The first characters of the key in monospace font. The full key is never shown again after creation.
• Rate limit: Shown as RPM (requests per minute) if configured.
• Allowed/blocked tools: Chip showing the count of allowed or blocked tools, if any are configured.
• Created by: The user who created the key and the creation date.
• Description: Optional text explaining what the key is for.

Creating an agent key

Click Create agent key in the top-right corner. The modal has these fields:

Monitor only mode

In monitor only mode, rules are checked and logged but never block or pause calls. Guardrails and approval rules are still evaluated, and so are the key's tool lists for calls through the MCP proxy, and for native tool calls when the key's "Also apply tool lists to native tool calls" setting is on. Each match shows in Activity as "Would block" or "Would need approval". No approval requests are created. Rate limits still apply, as does the circuit breaker on the MCP proxy.

To change the mode of an existing key, click the sliders icon on its row (Enforcement settings), pick a mode and click Save. The same window has the "Also apply tool lists to native tool calls" setting. Switching to Monitor only asks you to confirm; switching back to Enforce does not. Other admins get a notification whenever a key's mode changes.

Tool access control

You can restrict which MCP server tools an agent key can call through the proxy using two lists:

• Allowed tools: If set, the agent can only call tools in this list. Everything else is blocked.
• Blocked tools: If set, the agent can call any tool except those in this list.

If both lists are empty, the agent can access all tools. If both are set, the allowed list takes precedence: a tool must be in the allowed list and not in the blocked list.

The lists apply to native tool calls too (the agent's own tools, checked by the hook script or the Python SDK) only when Also apply tool lists to native tool calls is on for the key. The Tools column of the key list shows "MCP proxy only" or "MCP proxy and native calls".

Copying the key after creation

After you click Create key, a modal shows the full key. This is the only time you'll see it. Copy it immediately and store it securely.

The modal includes:

• The full key in a monospace box with a copy button.
• A warning that the key won't be shown again.
• A usage example showing a curl command with the key as a Bearer token.
• A reminder to use agent keys from backend services only.

Click I copied, continue to close the modal. If you lose the key, you'll need to create a new one.

Usage example

An agent authenticates with the gateway by passing its key as a Bearer token:

# List available tools
curl -X POST https://your-verifywise-host/v1/mcp \
  -H "Authorization: Bearer sk-mcp-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Call a tool
curl -X POST https://your-verifywise-host/v1/mcp \
  -H "Authorization: Bearer sk-mcp-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {"query": "quarterly revenue"}
    }
  }'

Key statuses

Agent keys have four possible statuses:

Revoking a key

To revoke an active key, click the ban icon on its row. A confirmation modal appears with the warning: "All requests using this key will be rejected immediately."

Revocation is instant, and the agent starts getting 401 errors on its next request. You can't un-revoke a key, so create a new one if you need to restore access.

Deleting a key

Only revoked or inactive keys can be deleted. The trash icon appears for non-active keys. Deleting a key removes it from the list permanently. Audit log entries referencing this key are preserved.

Rate limiting

Each key can have a requests-per-minute (RPM) limit. When the limit is hit, the gateway returns a rate-limited error. The agent should back off and retry.

If no rate limit is set on the key, there's no per-key throttling (though the gateway may still enforce global rate limits).

Permissions

Creating, revoking and deleting agent keys, and changing their mode, requires the Admin role. All authenticated users can view the key list (but not the key values, which are only shown once at creation).