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 > MCP Gateway > 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".
• 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:

Tool access control

You can restrict which tools an agent key can access 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.

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

Here's how an agent authenticates with the gateway using an agent key:

# 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. The agent will start getting 401 errors on its next request. You can't un-revoke a key. Create a new one if needed.

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 requires the Admin role. All authenticated users can view the key list (but not the key values, which are only shown once at creation).