Products & Surfaces

MCP authentication

MCP Surfaces support public access, API key authentication, and OAuth. Use a protected MCP Surface when you need to control access to its Capabilities.

How MCP authentication works

Choose an authentication mode based on the MCP client and access requirements:

  • OAuth: The client opens a browser authorization flow. Use OAuth for clients that support it, including Claude Desktop and Cursor.
  • API key: The client sends an API key with the mcp_ prefix as a Bearer token. Use API key authentication for clients that do not support OAuth.
  • Public: The MCP Surface accepts requests without authentication. Use this mode only for public tools.

When you use API key authentication, the request flow is:

  1. The MCP client sends a request with the API key in the Authorization header.
  2. Runtype validates the API key against the MCP Surface.
  3. The MCP client requests the available tools.
  4. The MCP client sends the API key with each tool call.
  5. Runtype validates the API key and executes the selected Capability.

Create MCP-specific 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.

To create an MCP API key, follow these steps:

  1. Open the MCP Surface.
  2. Open the Keys tab.
  3. Click Generate Key.
  4. Enter a descriptive name, such as MCP - Claude Desktop.
  5. Click Generate Key.
  6. Copy and store the API key securely.

Runtype returns the full API key when you create it. Production API keys are hashed and cannot be recovered after creation. You can reveal test API keys from the Keys tab later.

MCP API keys use the mcp_ prefix. Use a different API key for each MCP client or team member so you can revoke access independently.

Protect API keys

API key authentication stores the API key as plaintext in the MCP client’s configuration file. Protect the API key with these practices:

  • Do not commit MCP client configuration files to version control. Add them to .gitignore.
  • Use test API keys for local MCP clients.
  • Use production API keys only when necessary.
  • Rotate API keys regularly by generating replacement API keys.

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.
  4. Click the delete control for the API key.
  5. In the confirmation dialog, click Delete Key.

The API key stops working immediately. Update the MCP client configuration with a replacement API key if you need continued access.

Troubleshoot authentication errors

Use the following checks for common MCP authentication errors:

Invalid API key

Check these conditions when the MCP client reports an invalid API key:

  • The API key is revoked or deleted.
  • The API key contains a typo in the MCP client configuration.
  • The API key belongs to a different Surface. Each API key works only on the MCP Surface that issued it.

Permission denied

Check these conditions when a tool call returns a permission error:

  • The API key is scoped to different Capabilities.
  • The MCP Surface status is not Active. Draft and paused MCP Surfaces reject requests.

Check the MCP client’s output panel for detailed error messages from the MCP server.

Next steps

Continue with one of these guides: