Setting up an MCP Surface

An MCP (Model Context Protocol) Surface exposes your Product’s Capabilities as tools that AI assistants can discover and use. After you connect an MCP client, it can call your Flows and Agents from its chat interface.

What is MCP?

MCP is an open protocol that lets AI assistants interact with external tools and services. When you create an MCP Surface, Runtype publishes your Product’s Capabilities as tools for MCP clients to discover and invoke.

You can use an MCP Surface for workflows such as:

• Claude Desktop calls your data-retrieval Flow during analysis.
• Cursor calls your code-generation Agent during a coding session.
• VS Code calls your custom tools through the Cline extension or GitHub Copilot.

If your Product has no Capabilities, create a Flow or Agent first. When you create an MCP Surface from the launch panel, Runtype attaches the Product’s existing Capabilities automatically.

Before you begin

Add at least one Capability to your Product. The MCP setup panel shows an empty tool list when your Product has no Capabilities.

Create an MCP Surface

To add an MCP Surface to a Product, follow these steps:

1. Open your Product.
2. In the Product editor, click Add Surface.
3. Select MCP Server. The editor opens a Surface panel.
4. Click Save in the Product editor. The editor saves the Surface.

After you save the Surface, the setup panel prompts you to configure tools and connect an MCP client.

Configure tools

Use the Configure Tools step to choose which Capabilities the MCP Surface exposes as tools. Each Capability attached to your Product has an enable or disable toggle.

Use Enable All or Disable All to update every Capability at the same time. From the setup completion screen, click View Full Config to manage tools and connection settings.

Connect your AI IDE

In the Ship step, choose an authentication mode before you connect an AI IDE:

• OAuth: Use OAuth with clients that support MCP OAuth discovery, including Claude Desktop and Cursor.
• API Key: Use a Bearer token with clients that do not support OAuth or when you want key-based access.
• Public: Allow unauthenticated access. Use this mode only for public tools or testing.

Connect your client

The Ship tab provides a connection URL or JSON configuration, depending on the authentication mode. Copy it into your MCP client.

For client-specific instructions for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, JetBrains, and other MCP clients, continue with Connecting to MCP clients.

Manage your Surface

Use the following tabs to inspect your Surface, manage its endpoint and keys, and copy its connection details:

Overview

The Overview tab shows your Surface name, status, and key details. Before you connect an AI IDE, confirm that the Surface status is Active.

Endpoints

The Endpoints tab shows your MCP endpoint URL and MCP manifest URL. It also lets you copy each URL for use in client configurations.

You can override a Capability name or description for this Surface. Use these overrides when the same Capability appears on multiple Surfaces with different contexts.

For programmatic integrations, use the following URLs:

• MCP Endpoint: https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/mcp
• 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.

Keys

MCP Surfaces use API keys in API Key mode and as a fallback for clients that do not support OAuth. Create and manage keys in the Keys tab.

To create an API key, follow these steps:

1. Open the Keys tab.
2. Click Generate Key.
3. In Name (optional), enter a name for the key.
4. In Key Type, select Test or Production.
5. Optional: In Rate Limit (requests/minute), enter a per-minute limit.
6. Click Generate Key.
7. Copy the key and store it securely.

Production keys are stored as hashes and cannot be revealed after creation. Test keys are revealable and capped at 50 requests per day. In API Key mode, the Ship tab creates a default test key for the connection configuration.

Store API keys securely. Do not commit them to version control. Rotate a key immediately if someone exposes it.

Ship

Use the Ship tab to copy configuration for Claude Desktop, Cursor, and other MCP-compatible clients. In API Key mode, the tab also creates a default test key.

Call tools with JSON-RPC

Most clients use an MCP library that performs the initialize handshake and tool discovery. To integrate directly, send JSON-RPC 2.0 requests to the MCP endpoint.

The MCP endpoint accepts JSON-RPC 2.0 requests over HTTP POST at this URL:

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

For a protected Surface, send an API key in an Authorization header. The endpoint also accepts the X-API-Key header:

Authorization: Bearer mcp_YOUR_API_KEY
Content-Type: application/json

Replace YOUR_API_KEY with the key value. The full key includes the mcp_ prefix.

Protected Surfaces require authentication for initialize, tools/list, and tools/call. Public Surfaces accept these methods without authentication.

To list the tools available to your API key, send this JSON-RPC request:

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "method": "tools/list",
5
  "params": {}
6
}

The response includes each Capability available to the request as a tool and its JSON Schema:

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "result": {
5
    "tools": [
6
      {
7
        "name": "answer_questions",
8
        "description": "Answer questions about products and services",
9
        "inputSchema": {
10
          "type": "object",
11
          "properties": {
12
            "question": { "type": "string" }
13
          },
14
          "required": ["question"]
15
        }
16
      }
17
    ],
18
    "ttlMs": 300000,
19
    "cacheScope": "private"
20
  }
21
}

The ttlMs and cacheScope fields provide SEP-2549 freshness hints. ttlMs specifies how long a client can cache the tool list. cacheScope indicates that the list is private to the credential. Clients can ignore these hints and request the list again on every turn.

To call a tool, send its name and arguments in a tools/call request:

1
{
2
  "jsonrpc": "2.0",
3
  "id": 2,
4
  "method": "tools/call",
5
  "params": {
6
    "name": "answer_questions",
7
    "arguments": { "question": "What are your shipping options?" }
8
  }
9
}

The response returns a content array that usually contains text:

1
{
2
  "jsonrpc": "2.0",
3
  "id": 2,
4
  "result": {
5
    "content": [{ "type": "text", "text": "We offer standard, express, and overnight shipping." }]
6
  }
7
}

To retrieve public server metadata without authentication, send a GET request to 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. Protected manifests omit tool details until you authenticate.

The endpoint returns these JSON-RPC error codes:

Verify your setup

After you connect an AI IDE, run these checks to confirm that your Capabilities appear as available tools:

• In Claude Desktop, look for the tools icon in the chat interface.
• In Cursor, open the MCP section in the chat panel.
• In VS Code with Cline, open the Cline sidebar settings and view the available tools.

Ask the AI assistant to call one of your Capabilities by name. The client lists it as a tool and runs it when invoked.

Troubleshoot missing tools

If tools do not appear, check these conditions:

• Confirm that the Surface status is Active.
• Confirm that at least one Capability is enabled for the Surface.
• Reload the client after you add or change the configuration.

Troubleshoot authentication failures

If authentication fails, check these conditions:

• Confirm that the API key starts with mcp_ and belongs to this Surface.
• Send the key in an Authorization: Bearer header or an X-API-Key header.
• For OAuth, confirm that your client supports MCP OAuth discovery or use an API key.

Next steps

Continue with one of these guides:

• MCP authentication: choose and manage authentication modes.
• Scoping API keys to capabilities: restrict a key to selected Capabilities.
• Quickstart: build a social media post generator as a REST API: build a Product and expose a Capability through a Surface.