Products & Surfaces

Setting Up an MCP Surface

An MCP (Model Context Protocol) Surface turns your Runtype Capabilities into tools that AI assistants can discover and use directly. Once connected, AI IDEs like Claude Desktop, Cursor, and VS Code can call your Flows and Agents on demand from the 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, your Product’s Capabilities are automatically published as tools that any MCP-compatible client can discover and invoke.

This enables workflows like:

  • Claude Desktop calling your data retrieval Flow during analysis
  • Cursor invoking your code generation Agent in a coding session
  • VS Code using your custom tools through the Cline extension or GitHub Copilot

Your Product needs at least one Capability to expose as a tool. If you have not added one yet, create a Flow or Agent first. When you create an MCP Surface from the launch panel, the first Capability is added automatically.

Create an MCP Surface

  1. Open your Product.
  2. Find the Surfaces section.
  3. Click Add Surface.
  4. Select MCP Server.
  5. Configure the Surface.
  6. Click Create.

A setup wizard walks you through choosing which Capabilities to expose as tools and connecting to your AI IDE.

Configure tools

Choose which Capabilities to expose as MCP tools. Each Capability attached to your Product appears with an enable or disable toggle. Use Enable All or Disable All to update everything at once.

You can change which tools are enabled later from the Surface’s Endpoints tab.

Connect your AI IDE

The Ship step helps you connect your Surface to an AI IDE. Start by choosing an authentication mode:

  • OAuth — Recommended for Claude Desktop and Cursor. Paste the MCP server URL into your IDE and complete authentication in the browser.
  • API Key — Use a Bearer token for clients that do not support OAuth or when you want key-based access.
  • Public — No authentication required. Use this for public tools or quick testing.

Connect your client

The Ship tab provides a JSON config snippet you can copy directly into your client. For detailed setup instructions for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, JetBrains, and other MCP clients, see Connecting to MCP clients.

Manage your Surface

Overview

The Overview tab shows your Surface name, status, and key details. Make sure the Surface status is Active before you connect AI IDEs.

Endpoints

The Endpoints tab shows your MCP endpoint URL and lets you enable or disable individual Capabilities as tools.

You can also override a Capability name or description for this Surface. This is useful when the same Capability is used across multiple Surfaces with different contexts.

For programmatic integrations, the Advanced: Programmatic Integration section provides these endpoints:

  • MCP Server URL: https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/mcp
  • MCP Manifest: https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/mcp/.well-known/mcp.json

Keys

MCP Surfaces can use API keys for authentication. Create and manage keys in the Keys tab.

To create an API key:

  1. Go to the Keys tab.
  2. Click Generate API Key.
  3. Configure the key.
  4. Click Generate.
  5. Copy and store the key securely.

Production keys are hashed and cannot be recovered after creation. Generate a new key if one is lost. Test keys can be revealed later from the Keys tab.

The Ship tab can create a default test key for quick setup, so you do not need to create one manually to get started. Store API keys securely and never commit them to version control. Rotate keys immediately if they are exposed.

Ship

The Ship tab provides configuration snippets for Claude Desktop, Cursor, and other MCP-compatible clients. You can return to this tab anytime to copy connection details or create a quick-start key.

Calling tools over raw JSON-RPC

Most clients use an MCP library that performs the initialize handshake and tool discovery for you. If you are integrating directly, the Surface accepts JSON-RPC 2.0 requests over HTTP POST:

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

Authenticate with a Bearer token (or X-API-Key) using the mcp_ prefix. initialize is public; tools/list and tools/call require authentication on protected Surfaces.

$Authorization: Bearer mcp_xxx

List the tools available to your key:

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

The result contains each Capability exposed as a tool, with its JSON Schema:

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "result": {
5    "tools": [
6      {
7        "name": "answer_questions",
8        "description": "Answer user 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 are SEP-2549 freshness hints (how long a client may cache this tool list, and that the list is per-credential, not shared). They are advisory: clients may ignore them and re-list on every turn.

Call a tool by name with its arguments:

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 result returns a content array (typically text):

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

For capability discovery without authentication, fetch the public manifest at .../mcp/.well-known/mcp.json. Errors are returned as JSON-RPC error objects using standard codes (-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error); authentication failures return -32001 (authorization required) or -32002 (API key required).

Verify your setup

After you connect an AI IDE, confirm your Capabilities appear as available tools:

  • Claude Desktop: Look for the tools icon in the chat interface.
  • Cursor: Check the MCP section in the chat panel.
  • VS Code (Cline): Open the Cline sidebar settings to view available tools.

Try asking the AI assistant to use one of your Capabilities by name. It should appear as an available tool and run when invoked.

If tools are not appearing, check that your Product status is Active and that the Capabilities you want are enabled in the Endpoints tab.

Next steps