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

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:

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.

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:

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

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:

VS Code (GitHub Copilot)

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

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

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:

{
  "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:

{
  "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:

{
  "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:

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.
• 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: create and configure your Surface
• MCP authentication: manage keys and authentication
• Scoping API keys to capabilities: restrict access to selected Capabilities
• Adding capabilities to a Product: expose more tools