@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

``bash
npm install @runtypelabs/mcp-server


or


pnpm add @runtypelabs/mcp-server
`

Quick Start

$3

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

`json
{
"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.

$3

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

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

$3

`bash
RUNTYPE_API_KEY=tv_your_api_key npx runtype-mcp-server
`

$3

| 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

$3

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

$3

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)

$3

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

Parameters:

- flow_id: The flow ID to retrieve

$3

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

$3

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

$3

Get details of a specific record including its metadata.

Parameters:

- record_id: The record ID to retrieve

$3

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

$3

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

$3

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)

$3

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)

$3

Execute a Runtype tool directly.

Parameters:

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

$3

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 john@example.com"

> "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:

`typescript
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:

`typescript
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

`bash


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