MCP (Model Context Protocol)

Runflow supports the Model Context Protocol (MCP) in two ways:

MCP Server Connector — Connect to external MCP servers (Linear, GitHub, DeepWiki, etc.) and use their tools in your agents, just like any other connector
MCP Gateway — Expose your Runflow connectors (REST APIs, databases, MCP servers) as a single MCP endpoint for Claude Desktop, Cursor, or any MCP client

MCP Server Connector

Connect to any external MCP server and use its tools in your agents. The MCP server’s tools are auto-discovered and become regular connector resources — no manual mapping needed.

Setting Up

Portal:

Connectors > New Connector > MCP Server
Enter the server URL (e.g., https://mcp.linear.app/sse)
Select transport: SSE or Streamable HTTP
Configure authentication if required (Bearer Token, Basic Auth, or OAuth2)
After creation, click Sync Tools — Runflow connects to the MCP server, calls tools/list, and creates a resource for each tool

What happens during Sync:

Runflow opens a connection to the MCP server
Calls tools/list to discover all available tools
Creates a ConnectorResource for each tool (name, description, input schema)
Updates existing resources if the schema changed
Removes tools that no longer exist on the server
You can re-sync anytime to pick up changes

Using in Agents

MCP tools work exactly like REST or Database connector tools in agents. The agent calls them via the LLM’s tool-use capability:

import { Agent, openai, createConnectorTool } from '@runflow-ai/sdk';

const agent = new Agent({
  name: 'Project Manager',
  instructions: `You help manage Linear issues and projects.
    When the user asks about issues, use the Linear tools to search and list.
    When they want to create an issue, gather title and description first.`,
  model: openai('gpt-4o'),
  tools: {
    listIssues: createConnectorTool({
      connector: 'linear-mcp',
      resource: 'list-issues',
    }),
    createIssue: createConnectorTool({
      connector: 'linear-mcp',
      resource: 'create-issue',
    }),
    getIssue: createConnectorTool({
      connector: 'linear-mcp',
      resource: 'get-issue',
    }),
  },
});

// The agent decides which tool to call based on the user's message
const result = await agent.process({
  message: 'Show me the open bugs assigned to me',
});
// Agent calls list-issues with { assignee: "me", status: "In Progress", label: "Bug" }

Direct Invocation (Without Agent)

Call MCP tools directly in your code — useful in workflows, scripts, or custom logic:

import { connector } from '@runflow-ai/sdk';

// Linear: list issues
const issues = await connector('linear-mcp', 'list-issues', {
  assignee: 'me',
  limit: 10,
  status: 'In Progress',
});
console.log(issues.data.issues);

// Linear: create an issue
const newIssue = await connector('linear-mcp', 'create-issue', {
  title: 'Fix login bug',
  description: 'Users are getting 500 errors on login',
  teamId: 'TEAM-123',
  priority: 2,
});
console.log(newIssue.data.id); // "PROJ-456"

// DeepWiki: search documentation
const docs = await connector('deepwiki-mcp', 'ask-question', {
  repoName: 'anthropics/claude-code',
  question: 'How do MCP servers work?',
});

Using in Workflows

Combine MCP tools with other steps in a workflow:

import { flow, connector } from '@runflow-ai/sdk';

const bugTriageFlow = flow('bug-triage')
  .step('fetch-bugs', async () => {
    const result = await connector('linear-mcp', 'list-issues', {
      label: 'Bug',
      status: 'Triage',
      limit: 20,
    });
    return { bugs: result.data.issues };
  })
  .step('classify', {
    agent: classifierAgent,
    prompt: ({ results }) =>
      `Classify these bugs by severity:\n${JSON.stringify(results['fetch-bugs'].bugs.map(b => ({ id: b.id, title: b.title, description: b.description })))}`,
  })
  .step('update-priorities', async ({ results }) => {
    const classifications = results.classify;
    for (const bug of classifications.bugs) {
      await connector('linear-mcp', 'update-issue', {
        issueId: bug.id,
        priority: bug.severity === 'critical' ? 1 : bug.severity === 'high' ? 2 : 3,
      });
    }
    return { updated: classifications.bugs.length };
  })
  .build();

Example: Project Management Agent with Linear

A complete agent that manages a Linear workspace via MCP:

main.ts

import { identify } from '@runflow-ai/sdk/observability';
import { agent } from './agent';

export async function main(input: any) {
  identify(input.userId || input.metadata?.userId || 'anonymous');
  return agent.process(input);
}

agent.ts

import { Agent, openai, createConnectorTool } from '@runflow-ai/sdk';

const linear = {
  listIssues: createConnectorTool({ connector: 'linear-mcp', resource: 'list-issues' }),
  getIssue: createConnectorTool({ connector: 'linear-mcp', resource: 'get-issue' }),
  createIssue: createConnectorTool({ connector: 'linear-mcp', resource: 'create-issue' }),
  updateIssue: createConnectorTool({ connector: 'linear-mcp', resource: 'update-issue' }),
  searchIssues: createConnectorTool({ connector: 'linear-mcp', resource: 'search-issues' }),
  listTeams: createConnectorTool({ connector: 'linear-mcp', resource: 'list-teams' }),
};

export const agent = new Agent({
  name: 'Linear Assistant',
  instructions: `You are a project management assistant connected to Linear.

## Capabilities
- List, search, and filter issues
- Create new issues with proper team, priority, and labels
- Update issue status, assignee, and priority
- List teams and their members

## Behavior
- When listing issues, show a concise summary: ID, title, status, assignee
- When creating issues, always ask for the team if not specified
- Use "me" as assignee to filter the current user's issues
- For priority: 1 = Urgent, 2 = High, 3 = Medium, 4 = Low`,

  model: openai('gpt-4o'),
  tools: linear,
  memory: { maxTurns: 20 },
  observability: 'full',
});

Supported MCP Servers

Any server implementing the MCP protocol works. Some popular ones:

Server	URL	Transport	Auth	Description
Linear	`https://mcp.linear.app/sse`	SSE	Bearer Token (API Key)	Issue tracking, project management
DeepWiki	`https://mcp.deepwiki.com/mcp`	Streamable HTTP	None	Search and read GitHub repo documentation
Sentry	Varies	Streamable HTTP	Bearer Token	Error tracking and monitoring
Cloudflare	Varies	Streamable HTTP	Bearer Token	Workers, KV, D1, R2 management
Notion	Varies	Streamable HTTP	Bearer Token	Pages, databases, search

Check mcp.run or the MCP servers directory for a full list of available MCP servers.

Authentication

MCP Server connectors support three authentication types. The credential is stored encrypted and injected automatically when connecting:

Type	How it works	Example
Bearer Token	Sent as `Authorization: Bearer <token>`	Linear API Key, GitHub PAT
Basic Auth	Username + password as Base64	Internal services
OAuth2	Client credentials or authorization code with automatic token refresh	Slack, HubSpot

MCP Gateway

The MCP Gateway turns your Runflow connectors into an MCP endpoint. Configure in the portal what to expose, get a URL, and any MCP client can connect.

Why Use It

Unify tools — Combine REST APIs, databases, and MCP servers in one endpoint
No code needed — Configure everything in the portal
Secure — API Key authentication, resource-level permissions, credentials stay server-side
Observable — Every call logged with input/output, duration, and status

Creating a Gateway

MCP Gateway > New Gateway — set name, select API Key
Add Tools — pick resources from any of your connectors
Copy the URL — use in Claude Desktop, Cursor, or any MCP client

Example: Multi-Connector Gateway

A gateway that exposes tools from three different connector types:

Tool	Source	Type
`list_issues`	Linear MCP Server	MCP_SERVER
`create_contact`	HubSpot REST API	REST_API
`execute_query`	PostgreSQL Database	DATABASE
`read_wiki_structure`	DeepWiki MCP Server	MCP_SERVER

All accessible from a single URL:

https://api.runflow.ai/api/v1/gateways/my-gateway/mcp?apiKey=sk-xxx

Connecting Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "runflow": {
      "url": "https://api.runflow.ai/api/v1/gateways/my-gateway/mcp?apiKey=sk-your-key"
    }
  }
}

Restart Claude Desktop. The tools appear in the tools menu and Claude can call them.

Connecting Cursor

In Cursor settings, add an MCP server with the gateway URL.

Connecting via Claude Code

claude mcp add runflow --transport http \
  "https://api.runflow.ai/api/v1/gateways/my-gateway/mcp?apiKey=sk-your-key"

Tool Management

Action	Description
Add Tools	Select resources from any connector to expose
Enable/Disable	Toggle individual tools without removing them
Alias	Rename a tool for the MCP client (e.g., `list-issues` to `linear_issues`)
Remove	Remove a tool from the gateway

Observability

The Logs tab in the gateway detail page shows every tool call:

Status badge (success/error), tool name, duration
Expandable input/output for debugging
Filter by status and date range
Auto-refresh every 15 seconds
Pagination for high-volume gateways

Security

Feature	Description
API Key auth	Each gateway has its own API Key
Resource-level	Only explicitly added tools are exposed
Tenant isolation	Gateways scoped to tenant, no cross-tenant access
Server-side credentials	MCP clients never see your API keys, database passwords, or OAuth tokens
Stateless	No session state stored, any pod can handle requests

Testing with curl

If you prefer to test the MCP Gateway directly via HTTP before connecting an MCP client:

List available tools

curl -X POST "https://api.runflow.ai/api/v1/gateways/my-gateway/mcp?apiKey=sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Call a tool

curl -X POST "https://api.runflow.ai/api/v1/gateways/my-gateway/mcp?apiKey=sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_issues",
      "arguments": {
        "assignee": "me",
        "limit": 5
      }
    },
    "id": 2
  }'

The Accept: application/json, text/event-stream header is required by the MCP Streamable HTTP transport. The response comes as a Server-Sent Event with the JSON-RPC result in the data field.

Available MCP Tools (Runflow Public MCP)

The public MCP connector — the same one used by the Claude.ai directory listing and the official runflowai/claude-code-plugin — exposes 116 tools spanning agents, executions, prompts, connectors, knowledge bases, dashboards, flows, event aggregation, and more. It mirrors the internal MCP surface 1:1, so anything you can do via the API-key /api/v1/mcp endpoint is also reachable from Claude or any MCP-compatible client. Tools are gated by OAuth scopes:

Scope	Verbs	Notes
`mcp:read`	`list_`, `get_`, `check_`, `search_`, `render_`, `fetch_`	Read-only. Granted by default for every connected client.
`mcp:write`	`create_`, `update_`, `deploy_`, `promote_`, `publish_`, `save_`, `move_`, `reorder_`, `toggle_`, `set_`, `test_`, `validate_`, `compile_`, `execute_`, `chat_`, `clear_`, `export_*`	Mutations. Requested at OAuth consent.
`mcp:admin`	every `delete_*` tool	Destructive. Requires explicit `mcp:admin` in the OAuth authorize request — clients registered via Dynamic Client Registration must opt in.

A token without the required scope sees the tool as if it didn’t exist (no error, no listing).

Inventory by category

Category	Read	Write	Admin	Examples
Platform & docs	6	0	0	`get_platform_overview`, `get_recent_activity`, `search_docs`, `fetch_doc_page`
Agents	7	7	1	`list_agents`, `get_agent_code`, `create_agent`, `deploy_agent`, `chat_with_agent`, `delete_agent`
Executions & threads	7	0	0	`list_executions`, `get_execution_details`, `list_execution_threads`
Execution reviews	4	3	1	`list_execution_reviews`, `create_execution_review`, `export_execution_reviews_for_training`, `delete_execution_review`
Sessions	2	1	0	`list_sessions`, `get_session_history`, `clear_session`
Prompts	3	2	1	`get_prompt`, `render_prompt`, `create_prompt`, `update_prompt`, `delete_prompt`
Connectors (templates, instances, resources, execution)	4	9	2	`list_connector_templates`, `create_connector_instance`, `create_custom_connector`, `execute_connector`, `delete_*`
Credentials	2	3	1	`list_credentials`, `create_credential`, `test_credential`, `delete_credential`
Knowledge / vector stores / documents	3	3	2	`list_vector_stores`, `add_document`, `search_knowledge`, `delete_vector_store`
Data sources	1	3	1	`list_datasources`, `create_datasource`, `test_datasource`, `delete_datasource`
Triggers	1	3	1	`list_triggers`, `create_trigger`, `toggle_trigger`, `delete_trigger`
LLM providers	4	3	1	`list_llm_providers`, `list_provider_models`, `create_llm_provider`, `delete_llm_provider`
Dashboards — cards	3	4	1	`list_dashboard_cards`, `create_dashboard_card`, `move_dashboard_card`, `delete_dashboard_card`
Dashboards — tabs	1	3	1	`list_dashboard_tabs`, `create_dashboard_tab`, `reorder_dashboard_tabs`, `delete_dashboard_tab`
Event discovery	2	0	0	`get_event_names`, `get_event_properties`
Event aggregation & query	3	0	0	`aggregate_events`, `query_events`, `render_dashboard_card`
Flows (visual orchestration)	1	5	0	`get_flow_run`, `save_agent_flow`, `compile_flow`, `validate_flow`, `test_flow`, `deploy_flow`
Total	54	49	13	116 tools

The canonical source of truth is the MCP tools/list response — categories above match the comment headers in the backend allowlist file, and may shift as the surface evolves. If you need an exhaustive list for a given build, call tools/list against the gateway you’re connecting to.

Connecting via OAuth (DCR)

When a client connects through Dynamic Client Registration, the authorize request must include mcp:admin in scope to access any delete_* tool. A read-only listing in claude_desktop_config.json or the Claude.ai directory only needs the default mcp:read mcp:write scope.

Next Steps

Connectors

Create REST, Database, and other connectors

Tools

Build custom tools for agents

Agents

Use MCP tools in agents

Observability

Track gateway calls and metrics

Getting Started

CLI

Core Concepts

Real-World Examples

Advanced

Configuration

Extending Runflow

Help & Support

MCP (Model Context Protocol)

MCP Server Connector

Setting Up

Using in Agents

Direct Invocation (Without Agent)

Using in Workflows

Example: Project Management Agent with Linear

Supported MCP Servers

Authentication

MCP Gateway

Why Use It

Creating a Gateway

Example: Multi-Connector Gateway

Connecting Claude Desktop

Connecting Cursor

Connecting via Claude Code

Tool Management

Observability

Security

Testing with curl

List available tools

Call a tool

Available MCP Tools (Runflow Public MCP)

Inventory by category

Connecting via OAuth (DCR)

Next Steps

Connectors

Tools

Agents

Observability

​MCP Server Connector

​Setting Up

​Using in Agents

​Direct Invocation (Without Agent)

​Using in Workflows

​Example: Project Management Agent with Linear

​Supported MCP Servers

​Authentication

​MCP Gateway

​Why Use It

​Creating a Gateway

​Example: Multi-Connector Gateway

​Connecting Claude Desktop

​Connecting Cursor

​Connecting via Claude Code

​Tool Management

​Observability

​Security

​Testing with curl

​List available tools

​Call a tool

​Available MCP Tools (Runflow Public MCP)

​Inventory by category

​Connecting via OAuth (DCR)

​Next Steps

Connectors

Tools

Agents

Observability

MCP Server Connector

Setting Up

Using in Agents

Direct Invocation (Without Agent)

Using in Workflows

Example: Project Management Agent with Linear

Supported MCP Servers

Authentication

MCP Gateway

Why Use It

Creating a Gateway

Example: Multi-Connector Gateway

Connecting Claude Desktop

Connecting Cursor

Connecting via Claude Code

Tool Management

Observability

Security

Testing with curl

List available tools

Call a tool

Available MCP Tools (Runflow Public MCP)

Inventory by category

Connecting via OAuth (DCR)

Next Steps