> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # 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](/user-guide/products-surfaces/setting-up-an-mcp-surface). ## Authentication modes Each MCP Surface has one authentication mode. The following table describes the modes: | Mode | API keys accepted | Behavior | | -------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Keys Only** | Yes | Every request must include a valid API key. This is the default mode. | | **OAuth + Keys** | Yes | Every 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)** | No | Anyone 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: ```http 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](/user-guide/products-surfaces/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. > **Warning** > > 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](/user-guide/products-surfaces/scoping-api-keys-to-capabilities). ## 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 message | Cause | Fix | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `MCP surface not found` | The Product ID or Surface ID in the URL is wrong. | Copy the endpoint URL from the Surface again. | | `MCP surface is not active` | The Surface status is draft or paused. | Set the Surface status to **Active**. | | `API key required` | The 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 required` | The 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 key` | The 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 expired` | The 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 surface` | The 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_NAME` | The 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: * [Setting up an MCP surface](/user-guide/products-surfaces/setting-up-an-mcp-surface): create an MCP Surface and add Capabilities. * [Connecting to MCP clients](/user-guide/products-surfaces/connecting-to-mcp-clients): connect Claude Desktop, Cursor, VS Code, and other clients. * [Scoping API keys to capabilities](/user-guide/products-surfaces/scoping-api-keys-to-capabilities): restrict an API key to specific Capabilities.