@runtypelabs/mcp-server

A Model Context Protocol (MCP) server that exposes the Runtype AI platform to AI assistants like Claude Desktop.

Official MCP server package available on npm

What is MCP?

The Model Context Protocol allows AI assistants to interact with external tools and data sources. This server enables Claude and other MCP-compatible assistants to:

• Run AI workflows (flows)
• Manage data records
• Execute custom tools
• Run prompts against LLMs

Installation

npm install @runtypelabs/mcp-server
# or
pnpm add @runtypelabs/mcp-server

Quick Start

Option 1: Hosted Server (Recommended)

Use the Runtype-hosted MCP endpoint - no installation required:

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

This uses the MCP protocol endpoint on the main Runtype API.

Option 2: Local Installation

Install and run locally with Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "runtype": {
      "command": "npx",
      "args": ["runtype-mcp-server"],
      "env": {
        "RUNTYPE_API_KEY": "tv_your_api_key_here"
      }
    }
  }
}

Standalone

RUNTYPE_API_KEY=tv_your_api_key npx runtype-mcp-server

Environment Variables

| Variable | Required | Description | | ----------------- | -------- | ------------------------------------------------------ | | RUNTYPE_API_KEY | Yes | Your Runtype API key (starts with tv_) | | RUNTYPE_API_URL | No | Custom API URL (default: https://api.runtype.com/v1) |

Available Tools

dispatch

Execute a Runtype flow with optional record context and conversation messages. This is the primary way to run AI workflows.

Use when you need to:
- Run a saved flow by ID
- Create and run an inline flow with custom steps
- Continue a conversation by passing message history
- Process data through a multi-step AI workflow

Parameters:

• record (optional): Record context with id, name, type, or metadata
• flow: Flow to execute - either { id: "flow_xxx" } or inline definition with name and steps
• messages (optional): Conversation history as [{ role, content }]
• options (optional): Execution options like model_override, store_results

list_flows

List available Runtype flows to discover what workflows are available.

Parameters:

• limit: Number of flows to return (1-100, default: 20)
• cursor: Pagination cursor
• search: Search by name
• status: Filter by status (draft, active, paused, failed)

get_flow

Get details of a specific flow including its steps and configuration.

Parameters:

• flow_id: The flow ID to retrieve

run_flow

Execute an existing flow by ID. Simplified version of dispatch.

Parameters:

• flow_id: The flow ID to execute
• record_id (optional): Record to run the flow on
• variables (optional): Input variables
• model_override (optional): Override model for prompts

list_records

List records (data entities) in Runtype.

Parameters:

• limit: Number to return (1-100, default: 20)
• cursor: Pagination cursor
• type: Filter by type (e.g., "customer", "document")
• search: Search by name

get_record

Get details of a specific record including its metadata.

Parameters:

• record_id: The record ID to retrieve

create_record

Create a new record.

Parameters:

• type: Record type (e.g., "customer", "lead", "document")
• name: Human-readable name
• metadata (optional): Additional data as key-value pairs

update_record

Update an existing record's name or metadata.

Parameters:

• record_id: The record ID to update
• name (optional): New name
• metadata (optional): Metadata to merge with existing

search_records

Search records with advanced filtering.

Parameters:

• type: Filter by type
• metadata_keys: Records must have these keys
• min_fields / max_fields: Filter by field count
• limit: Number of results (1-100, default: 20)

list_tools

List available Runtype tools (external APIs, custom code, nested flows).

Parameters:

• limit: Number to return (1-100, default: 50)
• tool_type: Filter by type (flow, custom, external)
• active_only: Only show active tools (default: true)

execute_tool

Execute a Runtype tool directly.

Parameters:

• tool_id: The tool ID to execute
• parameters: Parameters for the tool (check tool schema)

run_prompt

Run a prompt directly against an LLM for quick one-off calls.

Parameters:

• prompt_id (optional): ID of a saved prompt
• prompt_text (optional): Inline prompt text
• model (optional): Model to use (e.g., "gpt-4", "claude-3-opus")
• variables (optional): Variables to substitute
• response_format: Expected format (text, json, markdown)

Example Interactions

Once configured, you can ask Claude things like:

"List my available flows"

"Run the 'Customer Analysis' flow on record rec_abc123"

"Create a new customer record for John Doe with email [email protected]"

"Execute my web search tool with query 'latest AI news'"

"Run this prompt: 'Summarize the key points in {{text}}' with the text being 'AI is transforming...'"

Programmatic Usage

You can also use the server programmatically:

import { createServer } from '@runtypelabs/mcp-server'

const server = createServer({
  apiKey: 'tv_your_api_key',
  baseUrl: 'https://api.runtype.com/v1', // optional
})

// Connect to your own transport
await server.connect(myTransport)

Or use the API client directly:

import { RuntypeApiClient } from '@runtypelabs/mcp-server'

const client = new RuntypeApiClient({
  apiKey: 'tv_your_api_key',
})

const flows = await client.listFlows({ limit: 10 })
const result = await client.dispatch({
  flow: { id: 'flow_abc123' },
  messages: [{ role: 'user', content: 'Hello!' }],
})

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run locally
RUNTYPE_API_KEY=tv_xxx pnpm start

Security Considerations

• Your API key has access to all flows and records in your Runtype workspace
• Consider creating a dedicated API key with limited permissions for MCP use
• The server runs locally and communicates with Claude via stdio
• API calls are made directly to Runtype's servers over HTTPS

License

MIT