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

Using Saved MCP Servers

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

Step 1: Add the Server

Step 2: Discover Available Tools

$
curl https://api.runtype.com/v1/mcp/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

1
import { FlowBuilder, RuntypeClient } from '@runtypelabs/sdk'
2
3
const client = new RuntypeClient({
4
  apiKey: process.env.RUNTYPE_API_KEY
5
})
6
7
const result = await new FlowBuilder()
8
  .createFlow({ name: 'Notion Agent' })
9
  .prompt({
10
    name: 'Agent',
11
    model: 'gpt-5.4',
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 })

1
for event in client.dispatch({
2
    "flow": {
3
        "name": "Notion Agent",
4
        "steps": [{
5
            "type": "prompt",
6
            "config": {
7
                "model": "gpt-5.4",
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 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-5.4",
>
          "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.

1
const result = await new FlowBuilder()
2
  .createFlow({ name: 'Notion Agent (passthrough)' })
3
  .prompt({
4
    name: 'Agent',
5
    model: 'gpt-5.4',
6
    userPrompt: 'Help me organize my Notion workspace',
7
    tools: {
8
      toolIds: ['mcp:mynotion:*']
9
    }
10
  })
11
  .run(client, { streamResponse: true })

$
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-5.4",
>
          "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

1
const 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
14
const result = await new FlowBuilder()
15
  .createFlow({ name: 'User Agent' })
16
  .prompt({
17
    name: 'Agent',
18
    model: 'gpt-5.4',
19
    userPrompt: 'Help the user manage their Notion workspace',
20
    tools: {
21
      mcpServers
22
    }
23
  })
24
  .run(client)

1
mcp_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
13
for event in client.dispatch({
14
    "flow": {
15
        "steps": [{
16
            "type": "prompt",
17
            "config": {
18
                "model": "gpt-5.4",
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:

The headers type carries an arbitrary map of HTTP header name → value, for servers that need two or more headers (for example a hosted MCP that requires both an X-Api-Key and an X-Base-URL). Every value may contain a {{secret:NAME}} reference, resolved from your managed secrets at request time exactly like token or password. The headers field is valid only on type: "headers", and the record must be non-empty with valid HTTP header names.

OAuth 2.1 authentication

Some MCP servers protect their tools with OAuth instead of a static token. For these servers, Runtype handles the full OAuth 2.1 authorization in the dashboard, so you authorize once in the browser and never paste a token by hand.

Auto-detection on URL entry

When you enter an MCP server URL in the dashboard, Runtype probes the server to find out whether it requires OAuth2. This uses RFC 9728 protected-resource discovery to locate the server’s authorization server.

If OAuth2 is detected, Runtype surfaces a Connect with OAuth2 option instead of asking you for a manual token. The discovered issuer and scopes appear so you can confirm you’re authorizing the right provider.

Authorizing in the browser

Clicking Connect with OAuth2 opens a popup where you sign in and approve access with the provider. Runtype uses PKCE for the exchange, so no client secret is handled in the browser.

After you approve, the popup closes and the server’s tools appear for selection. You can then pick the tools you want, exactly as you would for any other MCP server.

Discovery diagnostics

If OAuth2 is not detected, an expandable diagnostics panel shows what each discovery phase tried — the URL it probed, the response status, and any error. Use this to troubleshoot servers that should support OAuth2 but aren’t being detected.

Where OAuth2 setup works

OAuth2 setup, auto-detection, and tool discovery are available in both places you add an MCP server:

• Settings > Integrations > MCP Servers — the main MCP server management area.
• The agent tool-selection modal — when adding a server while choosing tools for an agent.

Previously-configured OAuth2 servers now appear correctly in the agent tool-selection modal, showing their discovered tool count rather than appearing unconfigured.

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

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

Combining with Other Tools

MCP tools work alongside other tool types:

1
tools: {
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

Troubleshooting

API Reference

Next Steps