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

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.

Before you begin

Add at least one Capability to your Product. The MCP setup shows an empty tool list when your Product has no Capabilities. For more information, see Adding capabilities to a product.

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 Surface panel shows the Connect to AI Assistants setup, starting at the Configure Tools step.

The setup has two steps: Configure Tools and Ship. After you finish the setup, Ship is also available as a tab in the Surface panel.

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.

Runtype derives each tool’s input schema from the Capability. For a Flow, the schema comes from the Flow’s input variables. A Capability without a schema accepts one string argument named input. Runtype passes the tool arguments to the Flow as inputs and also sends them to the Capability as a user message. For more information, see Flow variables and templates.

By default, each tool uses its Capability’s name and description. To give a Capability a different name or description on this Surface only, set exposedName (up to 100 characters) and exposedDescription on the Surface item with the PUT /v1/products/{id}/surfaces/{surfaceId}/items/{itemId} endpoint. The dashboard has no control for these overrides.

An Agent can’t finish over MCP if it pauses for a tool approval, asks the user for input, or calls a tool that runs on the client. The tool call returns an error instead. Expose these Agents on a Chat or AG-UI Surface, or turn off Tool approval in the Agent’s tool settings. For more information, see Agent tools.

Connect an MCP client

In the Ship step, select an authentication mode from the Connect with menu:

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

New MCP Surfaces use API Key mode. In API Key mode, the Ship step creates a test key and includes it in the configuration.

Copy the connection URL or JSON configuration from the Ship step into your MCP client. Claude Desktop doesn’t load remote servers from the claude_desktop_config.json file that the Ship step names. Add the server URL in Claude Desktop under Settings > Connectors instead. Connectors don’t send API keys, so use OAuth or Public mode for Claude Desktop.

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

Activate the Surface

New Surfaces start in Draft status. The MCP endpoint rejects every request until the Surface status is Active.

To activate the Surface, follow these steps:

1. On the setup completion screen, click View Full Config.
2. On the Overview tab, click the status menu and select Active. The banner shows “This surface is live and accepting requests”.

To stop traffic without deleting the Surface, select Paused or Draft. For more information, see Product versioning and status.

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. Use it to change the Surface status.

Endpoints

The Endpoints tab shows your MCP endpoint URL and MCP manifest URL, with a copy button for each:

• 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 in OAuth mode for clients that don’t support OAuth. Create and manage keys in the Keys tab.

The Keys tab also has an Authentication Mode menu with different labels for the same three modes. Keys Only is API Key, OAuth + Keys is OAuth, and Public (No Auth) is Public. For more information, see MCP authentication.

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. Click Generate Key.
6. Copy the key and store it securely.

Production keys are stored as hashes and can’t be revealed after creation. Test keys can be revealed again from the Keys tab.

The key dialog also shows a daily cap for test keys and a Rate Limit (requests/minute) field. An MCP Surface doesn’t apply either limit. MCP tool calls count only toward your plan’s daily execution limit. To limit what a client can call, use a scoped key.

Store API keys securely. Don’t commit them to version control. Rotate a key immediately if someone exposes it.

Ship

The Ship tab shows the same connection URL or JSON configuration as the Ship setup step. Use it to change the authentication mode with the Connect with menu and to copy the configuration again.

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:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "answer_questions",
        "description": "Answer questions about products and services",
        "inputSchema": {
          "type": "object",
          "properties": {
            "question": { "type": "string" }
          },
          "required": ["question"]
        }
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "private"
  }
}

The ttlMs field (300000, five minutes) says how long a client can cache the tool list. The cacheScope value private means that the list applies only to this credential. Clients can ignore both fields.

Tool names contain only letters, digits, underscores, and hyphens, up to 64 characters. Runtype replaces other characters with underscores, so a Capability named Answer Questions becomes the tool Answer_Questions. When two tools get the same name, Runtype adds a suffix such as _2. Use the name from tools/list in tools/call.

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

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "answer_questions",
    "arguments": { "question": "What are your shipping options?" }
  }
}

The response returns a content array that contains text:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "We offer standard, express, and overnight shipping." }]
  }
}

When the call starts a Runtype run, the result also carries the run’s ID in _meta, under the com.runtype/executionId key:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "We offer standard, express, and overnight shipping." }],
    "_meta": { "com.runtype/executionId": "exec_YOUR_EXECUTION_ID" }
  }
}

A call that fails after its run starts carries the same key. A call refused before a run starts, such as an unknown tool or a reached limit, carries no _meta. Use the ID to correlate logs, quote it in a support request, or open the run with GET /v1/runs/{executionId} and an API key from your Runtype account.

A failed tool call still returns a JSON-RPC result, not an error. The result has "isError": true, and the content text describes the failure:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Error: Tool not found: answer_question" }],
    "isError": true
  }
}

A tool call returns isError for an unknown tool name, a key that is scoped away from the tool, a reached daily execution limit, or a failure in the Flow or Agent.

Long-running tool calls

A tools/call request can run for up to five minutes. To receive MCP progress notifications while the call runs, include params._meta.progressToken in the request. The endpoint then streams the response as server-sent events. Requests without a progress token get a plain JSON response.

If an Agent is still running when the call returns, the result text includes the execution ID and an API path for following its progress.

Server metadata and errors

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:

If the Surface doesn’t exist or isn’t Active, the endpoint returns HTTP 404 with a plain JSON body, such as {"error":"MCP surface is not active"}, instead of a JSON-RPC error.

Verify your setup

To confirm that your tools work before you configure a client, send a tools/list request and a tools/call request to the MCP endpoint, as described in Call tools with JSON-RPC.

After you connect an MCP client, confirm that the client lists your Capabilities as tools. Connecting to MCP clients shows where each client lists its tools. Then ask the AI assistant to call one of your Capabilities by name.

Troubleshooting

The following sections cover the most common setup failures.

Tools don’t appear

If tools don’t appear, check these conditions:

• Confirm that the Surface status is Active. An inactive Surface returns HTTP 404 with the message MCP surface is not active.
• Confirm that at least one Capability is enabled for the Surface.
• Reload the client after you add or change the configuration.

Authentication fails

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.
• Confirm that the key hasn’t expired. An expired key returns API key has expired.
• For OAuth, confirm that your client supports MCP OAuth discovery or use an API key.

Next steps

Continue with one of these guides:

• Connecting to MCP clients: configure Claude Desktop, Cursor, and other clients.
• MCP authentication: choose and manage authentication modes.
• Scoping API keys to capabilities: restrict a key to selected Capabilities.
• Product versioning and status: understand the Active, Paused, and Draft statuses.
• Quickstart: build a social media post generator as a REST API: build a Product and expose a Capability through a Surface.