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.

Use this URL pattern:

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

Replace YOUR_PRODUCT_ID and YOUR_SURFACE_ID with the IDs from your Product and Surface. Find the exact URL in the Ship tab of your MCP Surface.

Choose an authentication mode

Select an authentication mode in the Ship tab. Use this table to choose the mode for your client:

In OAuth mode, the client completes the OAuth flow when you connect the URL. In API Key mode, create an API key in the Keys tab and include it in the client configuration. Runtype prefixes MCP Surface keys with mcp_.

Claude Desktop

Use OAuth or Public mode to connect a remote MCP Surface to Claude Desktop. Claude Desktop adds remote MCP servers through Settings > Connectors. It does not load remote servers from claude_desktop_config.json.

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:

1
{
2
  "servers": {
3
    "your-product": {
4
      "type": "http",
5
      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp"
6
    }
7
  }
8
}

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)

Add the MCP Surface to Cline with these steps:

1. Open the Cline panel.
2. Open Settings.
3. Open MCP Servers and click Edit MCP Settings.
4. Add the MCP server URL.
5. If you use API key authentication, add the Authorization: Bearer YOUR_API_KEY header. Replace YOUR_API_KEY with your API key.
6. Save the configuration and reopen the Cline panel.

Windsurf

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

1
{
2
  "mcpServers": {
3
    "your-product": {
4
      "serverUrl": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp",
5
      "headers": {
6
        "Authorization": "Bearer YOUR_API_KEY"
7
      }
8
    }
9
  }
10
}

Replace YOUR_PRODUCT_ID, YOUR_SURFACE_ID, and YOUR_API_KEY with your values. If your Surface uses OAuth or Public mode, omit the headers block.

JetBrains IDEs

Use these steps in IntelliJ IDEA, WebStorm, PyCharm, or another JetBrains IDE with AI Assistant enabled:

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. Replace YOUR_API_KEY with your API key.
6. Click OK.
7. Click Apply.

Any other MCP client

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

1
{
2
  "mcpServers": {
3
    "your-product": {
4
      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp",
5
      "headers": {
6
        "Authorization": "Bearer YOUR_API_KEY"
7
      }
8
    }
9
  }
10
}

Replace YOUR_PRODUCT_ID, YOUR_SURFACE_ID, and YOUR_API_KEY with your values. For OAuth-enabled or Public Surfaces, omit the headers block. A client that supports MCP OAuth discovery completes authentication automatically.

Use this URL to inspect the MCP manifest:

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

Replace YOUR_PRODUCT_ID and YOUR_SURFACE_ID with the IDs from your Product and Surface.

Verify your connection

After you connect, use these checks to confirm that the client lists your Capabilities as tools:

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

Ask the client to call one of your tools by name. If no tools appear, confirm that the Surface status is Active and that at least one Capability is enabled in the Endpoints tab.

Troubleshooting

Tools do not appear

If tools do not appear, run these checks:

• Confirm that the Surface status is Active.
• Confirm that at least one Capability is enabled in the Endpoints tab.
• Restart or reload the client after you add the configuration.
• If you use API key authentication, confirm that the key starts with mcp_ and remains active.

Authentication fails

If authentication fails, run these checks:

• Complete the browser authorization flow for OAuth.
• Check the API key and header for typos.
• Confirm that the API key belongs to this Surface.
• For more information, read MCP authentication.

Connection times out

If the connection times out, run these checks:

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

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