npm package: @runtypelabs/mcp-server
Description: Model Context Protocol (MCP) server for the Runtype AI platform - enables AI assistants to orchestrate flows, manage records, and execute tools
Author: Runtype Labs
Latest version: 0.3.0

# @runtypelabs/mcp-server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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

### Option 1: Hosted Server (Recommended)

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.

### Option 2: Local Installation

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"
      }
    }
  }
}
```

### Standalone

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