Runtype MCP server

Runtype hosts a Model Context Protocol (MCP) server that lets an AI client build and manage your Runtype account. You can create products, design and run flows, configure Surfaces, embed Persona chat widgets, and manage Agents, Records, logs, and runtime Tools. The client connects to Runtype instead of connecting Runtype to an external MCP server.

Distinguish the MCP features

Runtype supports MCP in three directions. Use the following table to distinguish these features:

Choose an MCP server

Choose the server that matches how your client discovers and runs tools. The two options are:

• Standard MCP server: Exposes one tool per operation, such as create_flow, list_records, and execute_tool. Choose it when your client browses a flat tool list and calls tools by name.
• Code Mode MCP server: Exposes a search and execute pair that runs JavaScript against the Runtype API. Choose it when your client writes code against the Runtype API instead of calling one tool per operation.

The following table lists the endpoint for each server:

Both servers send instructions when the client connects. These instructions describe the recommended call sequence.

Connect to the server

Run npx -y @runtypelabs/cli@latest onboard to connect Claude Code, Cursor, Codex, Gemini CLI, OpenCode, or VS Code and install the Runtype agent skills. For automated setup details, see Connect Runtype to coding agents. Use the instructions in this section for manual configuration.

Both servers support two authentication methods:

• Browser sign-in: The default. Add the server without credentials. The first connection opens a browser window where you sign in to Runtype.
• API key authentication: Send a Runtype API key as a bearer token. Use it when a browser is unavailable, such as with a headless coding agent or a CI job. Any Runtype API key works, including one obtained through agent self-registration.

Install Runtype in Claude Desktop

Claude Desktop installs Runtype as a bundled extension, so you don’t edit a configuration file.

To install the extension in Claude Desktop, follow these steps:

1. Download Runtype for Claude Desktop, a .mcpb bundle that is about 1 MB.
2. Double-click the downloaded file or drag it to Settings > Extensions in Claude Desktop. Confirm the installation.
3. Start a conversation and ask Claude to use Runtype, such as “list my Runtype products”. The first tool call opens a browser window where you can sign in or sign up for your Runtype account.

Claude Desktop stores the sign-in, so the browser prompt appears only on first use. To authenticate without a browser, open the extension settings and paste a Runtype API key into the optional Runtype API key field. The extension stores the key in your operating system keychain and sends it as a bearer token.

The extension connects Claude Desktop to the standard MCP server. The same tools, authentication methods, and call sequence apply to this connection.

Connect Claude Code

To add the standard MCP server with browser sign-in, run this command:

claude mcp add --transport http runtype https://api.runtype.com/v1/mcp/protocol

To add the standard MCP server with an API key, run this command:

claude mcp add --transport http runtype https://api.runtype.com/v1/mcp/protocol \
  --header "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your Runtype API key.

Connect another MCP client

To add the standard MCP server to another MCP client with an API key, use this configuration:

{
  "mcpServers": {
    "runtype": {
      "url": "https://api.runtype.com/v1/mcp/protocol",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your Runtype API key. To use browser sign-in instead, omit the headers object.

Connect to the Code Mode server

The Code Mode MCP server supports the same authentication methods as the standard MCP server. To add it to Claude Code with browser sign-in, run this command:

claude mcp add --transport http runtype-code https://code.runtype.com/mcp

To add it to another MCP client with an API key, use this configuration:

{
  "mcpServers": {
    "runtype-code": {
      "url": "https://code.runtype.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your Runtype API key. To use browser sign-in instead, omit the headers object.

Verify the connection

To confirm that the client reaches the organization you expect, ask the client to call the get_me tool on the standard MCP server. The tool returns your user ID, organization ID, and email address. From a terminal, you can run runtype mcp call get_me --json instead.

How browser sign-in works

When you sign in through the browser, Runtype creates an API key for your client in the organization that is active in your dashboard session. The key has the following properties:

• It’s named MCP Client (CLIENT_ID), where CLIENT_ID is the ID that your client registered.
• It has broad permissions to build and manage resources in that organization.
• It expires after 90 days. The server doesn’t refresh it, so you sign in again after it expires.

To revoke a client’s access, delete its key on Settings > API. For more information, see Managing API keys.

Call MCP from the Runtype CLI

The runtype CLI discovers and invokes either hosted server directly. You don’t need to register an MCP client or wait for individual tool commands to be added to the CLI.

Use these commands to discover, inspect, and call tools:

# Standard MCP (default)
runtype mcp tools
runtype mcp inspect create_flow
runtype mcp call list_flows -F limit=20 --json
# Code Mode MCP
runtype mcp tools --server code
runtype mcp call execute --server code -F code=@query.js --json
# Complete arguments object from a file or stdin
runtype mcp call create_flow --input arguments.json --json
cat arguments.json | runtype mcp call create_flow --input - --json

Use -f key=value for string values and -F key=value for JSON-typed values. With -F, prefix a file path with @ or use @- for stdin. Use --json-body for a complete inline arguments object. Use --json to preserve the complete MCP result for scripts.

Calls wait up to 930 seconds by default. Pass --timeout <ms> to set another positive millisecond deadline. Replace <ms> with the timeout in milliseconds.

Before you use --input - or -F key=@-, run runtype auth login or set RUNTYPE_API_KEY. The CLI doesn’t prompt interactively when the stream contains tool arguments.

The command uses your CLI API key and follows --api-url. For local or custom deployments, set RUNTYPE_MCP_URL or RUNTYPE_CODE_MCP_URL to override the inferred endpoint. The runtype mcp commands call the Runtype protocol servers. Use the separate runtype tools command to manage runtime Tools saved in your Runtype account.

Troubleshoot the connection

The following table lists common connection errors and how to fix them:

For more help with keys and sign-in, see Authentication issues.

Recommended call sequence

Follow this sequence with either server:

1. Call get_build_instructions before any create_* mutation. Pass a task value of build-product, generate-flow, or explain-capabilities. The tool returns platform rules, schemas, step types, and variable-system guidance for that task. For build-product, you can pass these optional parameters:
   • focus: One or more of commerce, embed, embed-fullscreen, subagents, skills, search, retrieval, operational-design, agent-design, and prompt-authoring, separated by commas. The response includes the full guide for each area. Without focus, the response lists those guides as topics to fetch when needed.
   • template: A starting hint of support-agent, webhook-router, slack-bot, or data-pipeline. To deploy a complete product instead, see Deploy example templates.
2. Use get_platform_documentation for deterministic lookups and search_documentation for prose questions. get_platform_documentation serves exact schema, type-definition, tool-catalog, embed, SDK, and dashboard-link references on demand. search_documentation searches the published docs corpus and returns a synthesized answer with citations. Use it for “how do I…” and “what is…” questions. Use get_platform_documentation when you need an exact contract.
3. Call list_tools to discover tools. Run user and platform tools with execute_tool, or attach configured integration tool IDs to an Agent or prompt step through tools.toolIds.
4. Report problems with submit_feedback. When an API call fails unexpectedly, a tool behaves in a confusing way, or a doc page is wrong, call submit_feedback with a category (api, mcp, documentation, sdk, cli, dashboard, or other), a short note, and the affected request_id or url. Any API key can submit, and the call costs no credits. The tool returns a receipt ID. Runtype redacts values that look like secrets, but do not include secrets in the note. The same endpoint is available over REST as POST /v1/agent-feedback.
5. Delegate multi-step work with delegate_to_runtype (accounts with the delegation feature). Describe the goal and the acceptance check once; Runtype’s own operator agent runs in the cloud inside your account, reads the build instructions itself, validates before it mutates, test-runs what it built, and returns a digest with ids and dashboard links. Progress streams while you wait (wait_seconds, up to 240). If it is still running, poll with check_delegation; if it asks a question (status: input_required), answer by calling delegate_to_runtype again with the same task_id. Destructive operations need allow_destructive: true. The same capability is available over REST as POST /v1/delegate-tasks.

The standard MCP server also offers this guidance as MCP prompts, which many clients show as slash commands. The prompts are build-product, generate-flow, explain-capabilities, and generate-proposal. For one task, use either a prompt or the get_build_instructions tool, not both.

What the server can do

The standard MCP server has more than 200 tools. To see the full list, call tools/list from your client or run runtype mcp tools. The following table groups common tools by area:

Compact list responses

The standard MCP server keeps discovery responses bounded. The following tools use view: "compact" by default: list_products, list_agents, list_flows, list_tools, list_records, list_collections, list_skills, list_schedules, list_agent_executions, and list_runs. The list_agent_executions tool is deprecated. To list an Agent’s runs, call list_runs with agent_id instead.

Compact responses retain the normal row shape. They shorten strings longer than 100 Unicode characters and append …. Call the matching get_* tool to retrieve complete values for one resource. Pass view: "full" when you need complete values across a page.

REST and Code Mode responses return full values when you omit view. To request compact rows, pass view=compact to a large collection endpoint, such as the endpoints that list Agents, flows, Records, Tools, or runs. For the fields that a compact run row omits, see List runs.

Nested runs fold under their parent

By default, list_runs returns root runs only. A run that another run started, such as a subagent run or a nested flow, appears under its parent instead of as its own row. One Agent run that started three subagents is one row, not four.

The following fields and parameters control how child runs appear:

• childCount on each row is the number of runs that name that row as their parent. A value of 0 means the run has no children.
• parent_execution_id returns the child runs of one parent.
• include_children: true lists child runs beside their parents.
• A filter that names a resource, such as agent_id, flow_id, conversation_id, or execution_id, returns every matching run, child runs included.

Discover tools with list_tools

list_tools returns your user-defined Tools, configured integration tools, and custom MCP server registrations by default. It also returns a builtinToolsAvailable summary that groups the 100+ built-in platform tools by category. The summary shows available tools without returning every built-in tool at once.

The summary groups built-in tools as follows:

• Small categories: The response inlines each tool’s id, name, and description for data_management, file_operations, image_generation, knowledge_retrieval, temporal, web_scraping, and web_search.
• Large categories: The response keeps commerce and third_party_api collapsed with a count and a drill-down hint. For third_party_api, the summary also shows the top vendors.

Every returned tool carries a source field. Its value is user, builtin, integration, or mcp-server:

• Pass user and builtin IDs to execute_tool without changing them.
• Attach integration IDs to an Agent or prompt step through tools.toolIds. The catalog includes only integrations configured for the account.
• An mcp-server row is a server registration. Its tools use mcp:<serverName>:<toolName> references after runtime discovery.

Parameters

Use the following table to choose list_tools parameters:

Deeper catalogs

The builtinToolsAvailable summary also includes a seeAlso array of resource URIs. Fetch these resources with resources/read for fuller documentation than the inline summary provides.

The following table lists the catalog resources and other commonly used resources:

To see every resource, call resources/list from your client.

Run platform tools with execute_tool

To run a user or platform tool, pass its id exactly as list_tools returns it. The response has the same shape as a user Tool execution. Integration tools use builtin:INTEGRATION:TOOL_NAME IDs, but those IDs are attached through tools.toolIds rather than passed to execute_tool.

Platform tool IDs use one of the following forms:

• builtin:TOOL_NAME: For example, builtin:firecrawl, builtin:gpt-image-2-5, or builtin:exa. Replace TOOL_NAME with the built-in tool name.
• platform:orthogonal:VENDOR:TOOL_NAME: For example, platform:orthogonal:apollo:people_match. Replace VENDOR and TOOL_NAME with the returned vendor and tool values.

A configurable built-in tool takes its instance settings in tool_config, the same settings an Agent’s toolConfigs entry carries. The server checks tool_config against the tool’s configuration fields. tool_config applies only to builtin: and platform: tools, and a user-defined Tool rejects it. For example, to run builtin:decision_judge against a published question set:

{
  "tool_id": "builtin:decision_judge",
  "parameters": { "state": "My card was charged twice for the same order." },
  "tool_config": { "questionSetId": "qset_YOUR_QUESTION_SET_ID", "version": 1 }
}

Replace qset_YOUR_QUESTION_SET_ID with your question set’s ID. A built-in result can also carry an optional metadata object for the caller. A judgment reports its resolved model, key source, token usage, and estimated cost in metadata.judgment. For the fields, see Call a configured instance over REST.

Chain platform tools from Code Mode

On the Code Mode server, the same catalog is reachable from inside execute as runtype.executeTool(toolId, parameters, toolConfig?). The method also accepts an object, runtype.executeTool({ toolId, parameters, toolConfig }), and returns { toolId, toolName, result, metadata? }.

The optional toolConfig carries a configurable built-in tool’s instance settings. For example, to ask a published question set about some state:

;async (runtype) => {
  const judged = await runtype.executeTool(
    'builtin:decision_judge',
    { state: 'My card was charged twice for the same order.' },
    { questionSetId: 'qset_YOUR_QUESTION_SET_ID', version: 1 }
  )
  return { answers: judged.result, model: judged.metadata?.judgment?.resolvedModelId }
}

result holds the answers, and metadata.judgment reports how the judgment ran. For the fields, see Call a configured instance over REST.

Built-in tools don’t appear in spec.methods. Discover them with search:

;(spec) => spec.builtinTools.filter((t) => /asset|screenshot/i.test(t.toolId + t.name))

Each entry is { toolId, name, category }. Provider-executed tools, such as native web search, aren’t listed because they attach to a prompt step through tools.toolIds and can’t run on their own.

Several executeTool calls inside one execute invocation run server-side, so intermediate values stay in the sandbox and never enter the model’s context. Use this when one tool’s output is large or binary and feeds another tool. For example, to screenshot a page and host the PNG:

;async (runtype) => {
  const open = await runtype.executeTool('builtin:browser:open', {
    url: 'https://example.com',
    viewport: { width: 1440, height: 900 },
  })
  const sessionId = open.result.sessionId
  const shot = await runtype.executeTool('builtin:browser:session-screenshot', {
    sessionId,
    format: 'png',
    fullPage: false,
  })
  const media = shot.result.find((p) => p?.type === 'media')
  const asset = await runtype.executeTool('builtin:store_asset', {
    content: media.data,
    contentType: 'image/png',
    visibility: 'public',
    filename: 'page.png',
  })
  await runtype.executeTool('builtin:browser:close', { sessionId })
  return asset.result
}

Deploy sandboxes

Use these tools to manage the lifecycle of Runtype Sandbox containers:

A successful deploy_sandbox call returns a previewUrl that you can open immediately to view the running result. To update the running code, call deploy_sandbox again with the returned sandboxId. Call destroy_sandbox after you finish to free the container.

Preview URLs are temporary. The container can sleep, be removed, or stop when the application fails. Use a preview to check a result, not to host an application.

Deploy example templates

Browse the Runtype examples. Use these tools to restore a complete product in your account by its example slug. The slug matches the identifier that the dashboard deploy page uses in /now?example=EXAMPLE_SLUG.

The example tools are:

create_product_from_example accepts these identifiers:

• slug: Identify a first-party example with /now?example=EXAMPLE_SLUG or runtype.com/examples/EXAMPLE_SLUG.
• session: Identify a shared session with /now?session=SESSION_ID. The server resolves it to that session’s hosted FPO document.
• url: Provide a pasted link. Supported links include dashboard /now links with example, session, templateUrl, or from parameters. These links can include templateParam:VARIABLE_KEY values, where VARIABLE_KEY is a template variable key. You can also provide example pages or direct HTTPS URLs to an FPO, FPO template, or A2A agent card.

To deploy an example, call list_example_templates first. Then call create_product_from_example with the chosen identifier. If required variable values are missing, the tool creates nothing. The response includes created: false, the missing variable keys, and the full variable specifications. Call the tool again with a complete variables object.

Both tools use the same quick-start import endpoints documented in Importing products. The result matches deploying the example from the dashboard.

Provide secrets without pasting them into chat

Most products need API keys or other credentials before they go live. Keep those values out of the conversation, because the client sends everything in the chat to the model. Use the following tools instead:

To enter the values, open the dashboard URL from get_secret_intake_manifest in a browser. The values that you enter there don’t appear in the conversation. Flows and Agents reference a secret as {{secret:KEY}}. For more information, see Managing secrets.

Manage record collections

Eight tools manage record collections. A collection registers a record type and can include a metadata schema. Runtype validates each record write according to the collection’s validation mode: off, warn, or enforce.

Use the following table to review the collection tools:

Use this adoption pattern: create a collection, infer a schema, save it in warn mode, dry-run with validate_collection_records, and switch to enforce after existing records conform. For the full walkthrough, see Defining a schema, which includes REST, SDK, and CLI equivalents.

After you add a schema, the runtype://records/collections MCP resource lists each collection’s slug, display name, validation mode, and full schema. The runtype_record_upsert, runtype_record_get, and runtype_record_list tools include the same field information in their descriptions. The annotations list each field’s name, type, and required status for every schematized collection.

Run flows with dispatch

When you call dispatch through the MCP server, debug mode is on by default. The response includes each step_complete.result and the final execution_complete summary. Use these results to verify which steps the flow ran. To turn debug mode off, set options.debugMode to false. To receive events as they happen, set options.streamResponse to true.

For work that can take longer than the client’s request timeout, pass async: true. The tool returns an execution ID right away. Poll it with get_execution_status.

To run a saved flow with input variables, use run_flow, which takes fewer parameters than dispatch. To test a conversational Agent, use execute_agent.

Watch product events

The server reads your organization’s product events, so a client can react when something needs attention. The event types are runtype.execution.failed, runtype.approval.requested, runtype.schedule.run_failed, runtype.eval.run_completed, runtype.conversation.human_takeover, runtype.skill.proposal_created, runtype.task.input_required, runtype.task.completed, runtype.task.failed, runtype.task.cancelled, runtype.signal.fired, and runtype.signal.cluster_appeared. A failed execution event also covers an interrupted run. To wait on a delegate_to_runtype task, call wait_for_event with name set to a task event and arguments set to { taskId }, then read the result with check_delegation. Each call watches one event type; to wake on any task outcome, run runtype events watch --task TASK_ID, which reads every type. For what each event carries, see Watch product events.

Use the following tools to read events:

Both poll tools take a name, a cursor, and an arguments object with the event’s filters, such as { "agentId": "YOUR_AGENT_ID" }. A filter that the event type doesn’t accept returns an error.

To watch for events without gaps, follow these steps:

1. Call wait_for_event without cursor. The call starts from now, returns no backlog, and returns the current cursor.
2. Call wait_for_event again with the returned cursor. The call returns when a matching event arrives, or with an empty events list after 50 seconds.
3. Store the cursor from every response, including a response with no events, and pass it on the next call.
4. If hasMore is true, call again right away to read the remaining events. With poll_events, wait nextPollMs milliseconds between calls otherwise.

The log keeps events for 7 days. If truncated is true, your cursor was older than the oldest retained event, and the events in between were skipped.

A host that supports the draft MCP Events extension can call the events/list and events/poll methods instead of the tools. The server advertises the extension both as events: {} and as extensions["io.modelcontextprotocol/events"] in its capabilities. events/poll takes name, arguments, cursor, maxEvents, and maxAgeMs, and returns the same result as poll_events.

On the Code Mode server, call runtype.listEventTypes() and runtype.pollEvents(params) inside execute. pollEvents takes name, arguments, cursor, maxEvents, maxAgeMs, and waitMs. Omit name to read every event type. waitMs defaults to 0 and must stay under the execute timeout, which is 60 seconds by default.

Next steps

Continue with one of these guides:

• MCP servers: connect Runtype to external MCP servers as flow tools
• Connecting to MCP clients: expose your product as an MCP Surface
• Working with tools: review the full tools overview
• Connect Runtype to coding agents: set up the server automatically with the runtype CLI
• Managing API keys: create, scope, and revoke the keys that the server uses
• Managing secrets: store the credentials that your products need
• Deploy a sandbox preview: deploy, redeploy, and destroy a sandbox preview
• Taking over messaging conversations: take over a conversation from the Agent and hand it back