> 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.

# Connecting to MCP clients

Connect an MCP (Model Context Protocol) Surface to MCP-compatible clients through its HTTP endpoint. Choose OAuth, an API key, or no authentication for the connection.

## Before you begin

Confirm that your MCP Surface is ready for a client connection:

* Create and save an MCP Surface. For more information, see [Setting up an MCP Surface](/user-guide/products-surfaces/setting-up-an-mcp-surface).
* Set the Surface status to **Active** on the **Overview** tab.
* Enable at least one Capability in the **Configure Tools** step of the Surface setup.

## Find the server URL

Every MCP Surface has an endpoint URL with this pattern:

```plaintext
https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp
```

Replace the following placeholders in this URL and in every example on this page:

* `YOUR_PRODUCT_ID`: the ID of your Product
* `YOUR_SURFACE_ID`: the ID of your MCP Surface
* `YOUR_API_KEY`: an MCP Surface API key, which starts with `mcp_`

Copy the exact URL from the **Ship** tab of your MCP Surface.

An **MCP Code Mode** Surface uses a URL that ends in `/mcp-code` instead of `/mcp`. The client sees two tools, `search` and `execute`, instead of one tool per Capability. Code Mode Surfaces support **API Key** and **Public** modes only.

## Choose an authentication mode

In the **Ship** tab, select an authentication mode from the **Connect with** menu. The following table describes each mode:

| Mode        | How it works                                                                 | Use it for                                                                               |
| ----------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **OAuth**   | The client discovers OAuth and prompts you to authorize in a browser.        | Clients that support OAuth, including Claude Desktop, Cursor, Claude Code, and Windsurf. |
| **API Key** | The client sends an API key as a bearer token in the `Authorization` header. | Automation, continuous integration, and clients without OAuth support.                   |
| **Public**  | The client sends no authentication.                                          | Public tools and testing.                                                                |

The **Keys** tab labels the same modes **OAuth + Keys**, **Keys Only**, and **Public (No Auth)**. New MCP Surfaces use **API Key** mode.

In **API Key** mode, the **Ship** tab creates a test key and includes it in the configuration that you copy. For production traffic, create a production key in the **Keys** tab. A client can send the key in an `Authorization: Bearer` header or an `X-API-Key` header.

In **OAuth** mode, clients without OAuth support can still connect with an API key from the **Keys** tab. When a client authorizes, Runtype issues it an API key named `OAuth Client (CLIENT_ID)` that expires after 90 days. The authorization page does not require a Runtype sign-in, so anyone with the Surface URL can authorize a client. For details and revocation steps, see [MCP authentication](/user-guide/products-surfaces/mcp-authentication).

## Claude Desktop

Claude Desktop adds remote MCP servers through **Settings > Connectors**. It does not load remote servers from `claude_desktop_config.json`, and it does not support API key authentication for remote servers. Use OAuth or Public mode.

To connect the MCP Surface to Claude Desktop, follow these steps:

1. Open **Settings > Connectors**.
2. Add a custom MCP connector.
3. Paste the MCP server URL from the **Ship** tab.
4. In OAuth mode, complete the authorization flow in the browser.

## Claude Code

Add the MCP Surface to Claude Code with one of these commands:

#### OAuth

Run this command to add the server. Claude Code prompts you to authorize in the browser.

```bash
claude mcp add --transport http your-product https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp
```

#### API key

Run this command to add the server with an API key:

```bash
claude mcp add --transport http your-product https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Run `claude mcp list` to confirm that the server connects. Run `claude mcp remove your-product` to disconnect it.

## Cursor

Connect the MCP Surface to Cursor with one of these methods:

#### OAuth

To add an OAuth-enabled MCP Surface, follow these steps:

1. Open **Customize > MCPs**.
2. Click **Add New MCP Server**.
3. Paste the MCP server URL from the **Ship** tab.
4. Complete the authorization flow in the browser.

#### API key

Add this configuration to `.cursor/mcp.json` in your project root or to `~/.cursor/mcp.json` for all projects:

**`.cursor/mcp.json`**

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "your-product": {
      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Reload the window after you save the file.

## VS Code (GitHub Copilot)

Add the MCP Surface to `.vscode/mcp.json` in your workspace:

#### OAuth

Add this configuration to `.vscode/mcp.json`. VS Code opens a browser for OAuth when the server first connects.

**`.vscode/mcp.json`**

```json title=".vscode/mcp.json"
{
  "servers": {
    "your-product": {
      "type": "http",
      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp"
    }
  }
}
```

#### API key

Add this configuration to `.vscode/mcp.json`:

**`.vscode/mcp.json`**

```json title=".vscode/mcp.json"
{
  "servers": {
    "your-product": {
      "type": "http",
      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Save the file. If VS Code asks you to trust the server, approve it. Open the Chat view and use **Configure Tools** to confirm that the tools are available.

## VS Code (Cline)

To add the MCP Surface to Cline, follow these steps:

1. Open the Cline panel.
2. Open **Settings**.
3. Open **MCP Servers** and click **Edit MCP Settings**. Cline opens its MCP settings file.
4. Add the server to the `mcpServers` object, as shown in the following example.
5. Save the file and reopen the Cline panel.

The following example adds the MCP Surface with API key authentication:

**`cline_mcp_settings.json`**

```json title="cline_mcp_settings.json"
{
  "mcpServers": {
    "your-product": {
      "type": "streamableHttp",
      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

If your Surface uses Public mode, omit the `headers` block.

## Windsurf

Add the MCP Surface to `~/.codeium/windsurf/mcp_config.json`:

**`~/.codeium/windsurf/mcp_config.json`**

```json title="~/.codeium/windsurf/mcp_config.json"
{
  "mcpServers": {
    "your-product": {
      "serverUrl": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

If your Surface uses OAuth or Public mode, omit the `headers` block.

## JetBrains IDEs

To add the MCP Surface in IntelliJ IDEA, WebStorm, PyCharm, or another JetBrains IDE with AI Assistant enabled, follow these steps:

1. Open **Settings > Tools > AI Assistant > Model Context Protocol (MCP)**.
2. Click **+** to add a server.
3. Select the HTTP connection type.
4. Enter the MCP server URL.
5. If you use API key authentication, add the `Authorization: Bearer YOUR_API_KEY` header.
6. Click **OK**.
7. Click **Apply**.

## Any other MCP client

If your client accepts an `mcpServers` JSON object, adapt this template:

**`Generic MCP config`**

```json title="Generic MCP config"
{
  "mcpServers": {
    "your-product": {
      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

For OAuth-enabled or Public Surfaces, omit the `headers` block. A client that supports MCP OAuth discovery completes authentication automatically.

## Verify your connection

Before you connect a client, test the Surface in the dashboard. In the Product editor, open the Surface's actions menu and click **Preview**. The preview panel lists the Surface's tools and lets you run one.

After you connect, check that the client lists your Capabilities as tools:

* **Claude Desktop**: Open a chat and check the tools list.
* **Claude Code**: Run `claude mcp list` and confirm the server status.
* **Cursor**: Open the MCP tools list in the chat panel.
* **VS Code (Copilot)**: Open **Configure Tools** in Chat and confirm the tools.

Ask the client to call one of your tools by name. Each enabled Capability appears as a tool named after the Capability. Characters other than letters, digits, hyphens, and underscores become underscores, and names are limited to 64 characters. For example, a Capability named `Summarize Ticket` appears as `Summarize_Ticket`. If two tools have the same name, one of them gets a numeric suffix such as `_2`.

To inspect the server manifest, open this URL:

```plaintext
https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp/.well-known/mcp.json
```

## Troubleshooting

Match the symptom or the error message in the client's logs to one of the following sections.

### Tools do not appear

Try the following fixes:

* Set the Surface status to **Active**. An inactive Surface returns `MCP surface is not active`.
* Confirm that at least one Capability is enabled for the Surface.
* Confirm that the Capability is also enabled on the Product. A Capability disabled on the Product does not appear on any Surface.
* If you use a scoped key, confirm that its scope includes the Capability. For more information, see [Scoping API keys to capabilities](/user-guide/products-surfaces/scoping-api-keys-to-capabilities).
* Reconnect or restart the client after you change the configuration or enable a Capability. Clients can cache the tool list for up to 5 minutes.

### Authentication fails

Try the following fixes:

* For OAuth, complete the browser authorization flow.
* For an API key, check the key and header for typos. The key must start with `mcp_`. The server ignores a key without this prefix and returns `API key required`, or `Authorization required` in OAuth mode.
* Confirm that the API key belongs to this Surface. A key from another Surface returns `Invalid API key`.
* If the error is `API key has expired`, replace the key. For a key issued through OAuth, reconnect the client to authorize again. These keys expire after 90 days. For a key that you created, create a key in the **Keys** tab and update the client configuration.

### Connection times out

Try the following fixes:

* Confirm that the URL matches the URL in the **Ship** tab.
* If a corporate network blocks outbound connections, try another network.

### A tool call fails after 5 minutes

Each tool call has a 5-minute limit. If a long-running Capability exceeds it, the client reports an error. Reduce the work that the Capability does in one call.

## Next steps

Continue with one of these guides:

* [Setting up an MCP Surface](/user-guide/products-surfaces/setting-up-an-mcp-surface): create and configure your Surface
* [MCP authentication](/user-guide/products-surfaces/mcp-authentication): manage keys and authentication
* [Scoping API keys to capabilities](/user-guide/products-surfaces/scoping-api-keys-to-capabilities): restrict access to selected Capabilities
* [Adding capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product): expose more tools