For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dashboard
User GuideDeveloper GuidesAPI Reference
User GuideDeveloper GuidesAPI Reference
  • Getting Started
    • Introduction
    • Authentication
    • Quickstart
  • Guides
    • Working with Tools
    • Runtime Tools
    • FPO Templates
    • Importing Products
  • Integrations
    • MCP Servers
Dashboard
LogoLogo
On this page
  • MCP Servers
  • Overview
  • Two Ways to Use MCP Servers
  • Using Saved MCP Servers
  • Step 1: Add the Server
  • Step 2: Discover Available Tools
  • Step 3: Use in Flows
  • Passthrough Mode (mcp:<server>:*)
  • Using Runtime MCP Servers
  • When to Use Runtime Servers
  • Example
  • Authentication Types
  • Tool ID Format
  • Server Configuration Options
  • Environment Support
  • Limits
  • Combining with Other Tools
  • Security
  • Troubleshooting
  • API Reference
  • Next Steps
Integrations

MCP Servers

Was this page helpful?
Previous
Built with

MCP Servers

MCP (Model Context Protocol) is an open standard for connecting AI models to external tools and data sources. Runtype supports both built-in MCP integrations and custom MCP servers.

Overview

MCP servers provide tools that AI models can call during flow execution. Unlike simple HTTP tools, MCP servers offer:

  • Tool discovery - Automatic detection of available tools
  • Rich schemas - Detailed parameter definitions
  • Stateful connections - Session management for complex workflows
  • Standardized protocol - Works with any MCP-compatible server

Two Ways to Use MCP Servers

ApproachBest ForHow to Reference
Saved serversReusable integrationstoolIds: ['mcp:servername:tool'] (curated) or toolIds: ['mcp:servername:*'] (passthrough — all current and future tools)
Runtime serversDynamic/per-user credentialsmcpServers: [{ id, url, auth }]

Using Saved MCP Servers

Save an MCP server once, use it across all flows.

Step 1: Add the Server

Dashboard
API
  1. Go to Settings > Integrations > MCP Servers
  2. Click Add Custom Server
  3. Enter the server URL and authentication
  4. Click Test Connection to verify
  5. Save the configuration

Step 2: Discover Available Tools

$curl https://api.runtype.com/v1/mcp/servers/mynotion/tools \
> -H "Authorization: Bearer YOUR_API_KEY"

Response:

1{
2 "data": [
3 {
4 "toolId": "mcp:mynotion:create_page",
5 "name": "create_page",
6 "description": "Create a new Notion page",
7 "parametersSchema": { ... }
8 },
9 {
10 "toolId": "mcp:mynotion:search_pages",
11 "name": "search_pages",
12 "description": "Search for pages",
13 "parametersSchema": { ... }
14 }
15 ]
16}

Step 3: Use in Flows

TypeScript SDK
1import { FlowBuilder, RuntypeClient } from '@runtypelabs/sdk'
2
3const client = new RuntypeClient({
4 apiKey: process.env.RUNTYPE_API_KEY
5})
6
7const result = await new FlowBuilder()
8 .createFlow({ name: 'Notion Agent' })
9 .prompt({
10 name: 'Agent',
11 model: 'gpt-4o',
12 userPrompt: 'Create a page about our Q4 goals',
13 tools: {
14 toolIds: [
15 'mcp:mynotion:create_page',
16 'mcp:mynotion:search_pages'
17 ]
18 }
19 })
20 .run(client, { streamResponse: true })
Python SDK
1for event in client.dispatch({
2 "flow": {
3 "name": "Notion Agent",
4 "steps": [{
5 "type": "prompt",
6 "config": {
7 "model": "gpt-4o",
8 "userPrompt": "Create a page about our Q4 goals",
9 "tools": {
10 "toolIds": [
11 "mcp:mynotion:create_page",
12 "mcp:mynotion:search_pages"
13 ]
14 }
15 }
16 }]
17 }
18}):
19 print(event)
cURL
$curl https://api.runtype.com/v1/dispatch \
> -H "Authorization: Bearer YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "flow": {
> "name": "Notion Agent",
> "steps": [{
> "type": "prompt",
> "config": {
> "model": "gpt-4o",
> "userPrompt": "Create a page about our Q4 goals",
> "tools": {
> "toolIds": [
> "mcp:mynotion:create_page",
> "mcp:mynotion:search_pages"
> ]
> }
> }
> }]
> }
> }'

Passthrough Mode (mcp:<server>:*)

To attach every tool a saved server exposes — current and future — include a single wildcard entry in toolIds:

1{
2 "tools": {
3 "toolIds": ["mcp:mynotion:*"]
4 }
5}

The wildcard is expanded into concrete tool ids at execution time, so:

  • New tools added to the upstream MCP server appear automatically — no need to re-edit the agent.
  • Approval rules, toolConfigs, perToolLimits, and usage tracking still operate on real, fully-qualified tool ids.
  • If both a wildcard and curated picks are present for the same server (mcp:mynotion:* + mcp:mynotion:create_page), the wildcard wins and the curated picks are skipped.

Use passthrough when you trust the server end-to-end and want the agent to pick up new capabilities without configuration changes. Use the curated form (specific tool ids) when you want an explicit, audited subset.

TypeScript SDK
1const result = await new FlowBuilder()
2 .createFlow({ name: 'Notion Agent (passthrough)' })
3 .prompt({
4 name: 'Agent',
5 model: 'gpt-4o',
6 userPrompt: 'Help me organize my Notion workspace',
7 tools: {
8 toolIds: ['mcp:mynotion:*']
9 }
10 })
11 .run(client, { streamResponse: true })
cURL
$curl https://api.runtype.com/v1/dispatch \
> -H "Authorization: Bearer YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "flow": {
> "name": "Notion Agent (passthrough)",
> "steps": [{
> "type": "prompt",
> "config": {
> "model": "gpt-4o",
> "userPrompt": "Help me organize my Notion workspace",
> "tools": { "toolIds": ["mcp:mynotion:*"] }
> }
> }]
> }
> }'

Using Runtime MCP Servers

Pass server configuration inline for dynamic use cases.

When to Use Runtime Servers

  • Multi-tenant apps where each user has their own credentials
  • Testing new servers before saving
  • One-off integrations
  • Dynamic server URLs

Example

TypeScript SDK
1const mcpServers = [{
2 id: 'user_notion',
3 name: 'User Notion',
4 url: 'https://notion-mcp.example.com/mcp',
5 auth: {
6 type: 'bearer',
7 token: userCredentials.notionToken // Per-user token
8 },
9 timeout: 30000,
10 transport: 'streamable_http',
11 allowedTools: ['create_page', 'search_pages'] // Optional filter
12}]
13
14const result = await new FlowBuilder()
15 .createFlow({ name: 'User Agent' })
16 .prompt({
17 name: 'Agent',
18 model: 'gpt-4o',
19 userPrompt: 'Help the user manage their Notion workspace',
20 tools: {
21 mcpServers
22 }
23 })
24 .run(client)
Python SDK
1mcp_servers = [{
2 "id": "user_notion",
3 "name": "User Notion",
4 "url": "https://notion-mcp.example.com/mcp",
5 "auth": {
6 "type": "bearer",
7 "token": user_credentials["notion_token"]
8 },
9 "timeout": 30000,
10 "allowedTools": ["create_page", "search_pages"]
11}]
12
13for event in client.dispatch({
14 "flow": {
15 "steps": [{
16 "type": "prompt",
17 "config": {
18 "model": "gpt-4o",
19 "userPrompt": "Help the user manage their Notion workspace",
20 "tools": {
21 "mcpServers": mcp_servers
22 }
23 }
24 }]
25 }
26}):
27 print(event)

Authentication Types

MCP servers support multiple authentication methods:

TypeFieldsExample
bearertoken{"type": "bearer", "token": "xyz"}
api_keyheaderName, token{"type": "api_key", "headerName": "X-API-Key", "token": "xyz"}
basicusername, password{"type": "basic", "username": "user", "password": "pass"}
custom_headerheaderName, token{"type": "custom_header", "headerName": "X-Custom", "token": "val"}
none-{"type": "none"}

Tool ID Format

MCP tool IDs follow this pattern:

mcp:<serverName>:<toolName>

Examples:

  • mcp:context7:resolve-library-id - Context7 documentation server
  • mcp:myslack:send_message - Your saved Slack server
  • mcp:github:create_issue - Your saved GitHub server

For runtime servers, tool IDs become:

mcp:custom_<serverId>:<toolName>

The reserved * toolName is the passthrough wildcard — see Passthrough Mode above:

mcp:<serverName>:*

Server Configuration Options

FieldRequiredDescription
idYesUnique identifier (used in tool IDs)
nameNoDisplay name for UI
urlYesMCP server endpoint URL
authNoAuthentication configuration
timeoutNoRequest timeout in ms (default: 30000, max: 60000)
transportNostreamable_http (default) or rest
allowedToolsNoArray of tool names to enable (all if omitted)
enabledNoWhether server is active (default: true)

Environment Support

Saved servers can have environment-specific configurations:

$# Development credentials
$curl -X POST https://api.runtype.com/v1/mcp/servers \
> -d '{
> "name": "notion",
> "url": "https://notion-mcp.example.com/mcp",
> "auth": { "type": "bearer", "token": "dev_token" },
> "environment": "development"
> }'
$
$# Production credentials
$curl -X POST https://api.runtype.com/v1/mcp/servers \
> -d '{
> "name": "notion",
> "url": "https://notion-mcp.example.com/mcp",
> "auth": { "type": "bearer", "token": "prod_token" },
> "environment": "production"
> }'

Specify environment in dispatch:

1{
2 "options": {
3 "environment": "production"
4 }
5}

Limits

LimitValue
Max servers per step5
Max timeout60 seconds
Tool discovery cache5 minutes

Combining with Other Tools

MCP tools work alongside other tool types:

1tools: {
2 toolIds: [
3 'mcp:notion:create_page', // Saved MCP server, specific tool
4 'mcp:linear:*', // Saved MCP server, all current + future tools
5 'builtin:dalle', // Built-in tool
6 'tool_abc123' // Custom saved tool
7 ],
8 mcpServers: [
9 { id: 'dynamic', ... } // Runtime MCP server
10 ],
11 runtimeTools: [
12 { name: 'custom', ... } // Runtime tool
13 ]
14}

Security

Credential Security

  • Auth tokens are encrypted at rest for saved servers
  • Runtime credentials are never logged or stored
  • Use environment variables, never hardcode tokens
  • Limit tool access with allowedTools when possible

Troubleshooting

Connection timeout
  • Check the server URL is accessible
  • Increase timeout value (max 60000ms)
  • Verify firewall/network rules
Authentication failed
  • Verify token is valid and not expired
  • Check auth type matches server expectations
  • For api_key, ensure headerName is correct
Tools not appearing
  • Call /mcp/servers/{name}/tools to verify discovery
  • Check allowedTools filter if set
  • Ensure server implements tools/list endpoint

API Reference

EndpointDescription
GET /mcp/serversList saved MCP servers
POST /mcp/serversAdd new MCP server
GET /mcp/servers/:nameGet server details
PATCH /mcp/servers/:nameUpdate server config
DELETE /mcp/servers/:nameRemove server
GET /mcp/servers/:name/toolsList server’s tools
GET /mcp/toolsList all configured MCP tools
POST /mcp/discoverDiscover tools from a URL

Next Steps

Working with Tools

Complete tools overview

Runtime Tools

Inline tool definitions

Building Flows

Create flows with tools

AI Providers

Configure AI models