Products & Surfaces

Connecting to MCP clients

Every MCP Surface exposes a standard HTTP endpoint that any MCP-compatible client can connect to. This page covers setup for the most popular clients and gives you a JSON config you can adapt for anything else.

Your MCP server URL follows this pattern:

https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/mcp

Find the exact URL in the Ship tab of your MCP Surface.

Authentication modes

Choose the mode that fits your client and security needs. You set this when creating the Surface or from the Ship tab later.

ModeHow it worksBest for
OAuthClient discovers auth automatically; user approves in-browserClaude Desktop, Cursor, Claude Code, Windsurf
API KeyPass a Bearer token in headersAutomation, CI, clients without OAuth
PublicNo authenticationQuick testing, public tools

With OAuth, most clients handle the flow automatically when you paste the URL. With API Key, you create a key in the Keys tab (keys use the mcp_ prefix) and include it in the config.

Claude Desktop

Open claude_desktop_config.json and add:

claude_desktop_config.json
1{
2  "mcpServers": {
3    "your-product": {
4      "url": "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp"
5    }
6  }
7}

Restart Claude Desktop. You will be prompted to authorize in the browser on first connection.

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Open the file from Settings > Developer > Edit Config in Claude Desktop.

Claude Code

Run this in your terminal:

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

Claude Code prompts you to authorize in the browser.

Use claude mcp list to verify the server appears, and claude mcp remove your-product to disconnect.

Cursor

  1. Open Settings (Cmd/Ctrl + ,).
  2. Search for MCP.
  3. Click Add new MCP server.
  4. Paste the MCP server URL from the Ship tab.
  5. Authorize in the browser prompt.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

.vscode/mcp.json
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}

VS Code discovers the server when you open the workspace. Use the Copilot chat panel to verify tools are available.

VS Code (Cline)

  1. Click the Cline icon in the sidebar.
  2. Open Settings (gear icon).
  3. Scroll to MCP Servers and click Edit MCP Settings.
  4. Add your server URL and, if using API Key auth, the Bearer header.
  5. Save and reopen the Cline sidebar.

Windsurf

Add to your Windsurf MCP config (.windsurf/mcp.json or via Settings > MCP):

.windsurf/mcp.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}

Omit the headers block if your Surface uses OAuth or is public.

JetBrains IDEs

In any JetBrains IDE (IntelliJ, WebStorm, PyCharm, etc.) with AI Assistant enabled:

  1. Open Settings > Tools > AI Assistant > MCP Servers.
  2. Click + to add a server.
  3. Enter the MCP server URL.
  4. If using API Key auth, add the Authorization: Bearer YOUR_API_KEY header.
  5. Click OK and restart the IDE.

Any other MCP client

The JSON config structure is the same across most clients. Adapt this template:

Generic MCP config
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}

For OAuth-enabled Surfaces, drop the headers block entirely. The client will negotiate auth automatically if it supports MCP OAuth discovery.

The MCP manifest is available at:

https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/mcp/.well-known/mcp.json

Verify your connection

After connecting, confirm your Capabilities appear as tools:

  1. Claude Desktop — look for the tools icon (hammer) in the chat input area.
  2. Claude Code — run claude mcp list and check for your server name.
  3. Cursor — open the MCP section in the chat panel sidebar.
  4. VS Code (Copilot) — look for the tools indicator in the Copilot chat.

Try asking the AI to use one of your tools by name. If tools do not appear, check that the Surface status is Active and that Capabilities are enabled in the Endpoints tab.

Troubleshooting

Tools not appearing:

  • Verify the Surface status is Active in Runtype.
  • Check that at least one Capability is enabled in the Endpoints tab.
  • Restart or reload the client after adding the config.
  • For API Key auth, confirm the key uses the mcp_ prefix and has not been revoked.

Authentication errors:

  • OAuth: make sure you completed the browser authorization flow.
  • API Key: check for typos and that the key matches the Surface, not a different one.
  • See MCP authentication for details.

Connection timeout:

  • Confirm the URL is correct (check the Ship tab for the canonical URL).
  • Some corporate networks block outbound connections — try from a different network.

Next steps