Skip to navigation
Products & Surfaces

MCP authentication

Choose how MCP clients authenticate to an MCP Surface, then create, protect, and revoke the API keys that give them access.

Before you begin, set up an MCP Surface and set its status to Active. For instructions, read Setting up an MCP surface.

Authentication modes

Each MCP Surface has one authentication mode. The following table describes the modes:

ModeAPI keys acceptedBehavior
Keys OnlyYesEvery request must include a valid API key. This is the default mode.
OAuth + KeysYesEvery request must include a valid API key. Clients that support MCP OAuth discovery can also get a key through a browser authorization.
Public (No Auth)NoAnyone with the Surface URL can list and call its tools. Use this mode only for public demos or open tools.

With Keys Only and OAuth + Keys, Runtype checks the API key on every request, including tool listing and tool calls. The key must belong to this MCP Surface.

A client sends the API key as a Bearer token in the Authorization header:

Authorization: Bearer mcp_YOUR_KEY

Replace mcp_YOUR_KEY with the full API key. Clients that can’t send a Bearer token can send the key in an X-API-Key header instead. For client configuration examples, read Connecting to MCP clients.

Set the authentication mode

To set the authentication mode, follow these steps:

  1. Open the MCP Surface.
  2. Open the Keys tab.
  3. In Authentication Mode, select Keys Only, OAuth + Keys, or Public (No Auth).

A mode change affects existing connections in these ways:

  • Public (No Auth) stops API key checks and hides key management in the Keys tab. Your existing keys stay stored and work again when you switch back to a mode that uses keys.
  • Switching from OAuth + Keys to Keys Only stops new OAuth authorizations. Keys that clients already got through OAuth keep working until you delete them.

What happens when a client uses OAuth

When a Surface uses OAuth + Keys and a client connects without an API key, the client starts OAuth discovery:

  1. The client opens a browser page titled Authorize followed by your Product name. The page lists the tools on the Surface.
  2. You click Authorize or Deny.
  3. If you click Authorize, the client receives an API key and uses it for later requests.

A key that a client gets through OAuth has these properties:

  • It appears in the Keys tab with the name OAuth Client (CLIENT_ID), where CLIENT_ID is the ID that the client registered.
  • It can call every Capability on the Surface. Capability scoping doesn’t apply to it.
  • It expires after 90 days. The client must then authorize again.

The authorization page doesn’t require a Runtype sign-in. Anyone who has the Surface URL and an OAuth-capable client can get a key with access to every tool on the Surface. To limit access to people you give keys to, use Keys Only. To restrict a client to specific Capabilities, use Keys Only and give it a scoped key.

Create MCP API keys

Create a separate API key for each MCP client or team member. You can then revoke one API key without affecting other connections. MCP API keys use the mcp_ prefix.

To create an MCP API key, follow these steps:

  1. Open the MCP Surface.
  2. Open the Keys tab.
  3. Click Generate Key.
  4. Optional: In Name (optional), enter a descriptive name, such as MCP - Claude Desktop.
  5. In Key Type, select one of these options:
    • Test: for local development. You can reveal a test key again later from the Keys tab.
    • Production: for deployed clients. Runtype stores only a hash of the key, so you can’t view it again after you create it.
  6. Click Generate Key.
  7. Copy the API key and store it securely.

The Key Type option describes test keys as capped at 50 requests a day, and the dialog also has a Rate Limit (requests/minute) field. An MCP Surface doesn’t apply the daily cap or the per-minute limit, so leave Rate Limit (requests/minute) empty. To stop a client from using a key, delete the key.

Protect API keys

An MCP client stores the API key as plaintext in its configuration file. Protect the API key with these practices:

  • Don’t commit MCP client configuration files to version control. Add them to .gitignore.
  • Use test API keys for local MCP clients.
  • Use production API keys for deployed clients. No one can reveal a production API key from the Keys tab.
  • Rotate API keys. To rotate a key, generate a replacement, update the client configuration, and then delete the old key.

Revoke MCP access

To revoke an MCP API key, follow these steps:

  1. Open the MCP Surface.
  2. Open the Keys tab.
  3. Find the API key that you want to revoke. A client connected through OAuth has a key named OAuth Client (CLIENT_ID).
  4. Click the delete icon for the API key.
  5. In the confirmation dialog, click Delete Key.

The API key stops working immediately. To keep access for that client, update its configuration with a replacement API key, or authorize it again through OAuth.

Troubleshoot authentication errors

Check the MCP client’s logs for the error message that the server returned. The following table lists common messages:

Error messageCauseFix
MCP surface not foundThe Product ID or Surface ID in the URL is wrong.Copy the endpoint URL from the Surface again.
MCP surface is not activeThe Surface status is draft or paused.Set the Surface status to Active.
API key requiredThe Surface uses Keys Only, and the request has no key that starts with mcp_. A Product API key or account API key doesn’t work on an MCP Surface.Send an MCP API key from the Surface’s Keys tab.
Authorization requiredThe Surface uses OAuth + Keys, and the request has no MCP API key.Complete the OAuth authorization in the browser, or add an MCP API key to the client configuration.
Invalid API keyThe key is deleted, contains a typo, or belongs to a different Surface. Each key works only on the MCP Surface that issued it.Check the key in the client configuration, or generate a new key.
API key has expiredThe key is past its expiry date. Keys from OAuth expire after 90 days.For an OAuth key, authorize the client again. For other keys, generate a new key.
OAuth is not enabled for this surfaceThe browser authorization page opened, but the Surface doesn’t use OAuth + Keys.Set the authentication mode to OAuth + Keys, or use an API key.
Access denied to tool: TOOL_NAMEThe key is scoped to other Capabilities.Use a key whose scope includes that Capability.

A scoped key lists only the tools for the Capabilities in its scope. If a tool is missing from the client’s tool list, check the key’s scope.

Next steps

Continue with one of these guides: