> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP (Model Context Protocol)
> Connect to external MCP servers and expose your connectors as an MCP Gateway
Runflow supports the **Model Context Protocol (MCP)** in two ways:
1. **MCP Server Connector** — Connect to external MCP servers (Linear, GitHub, DeepWiki, etc.) and use their tools in your agents, just like any other connector
2. **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:**
1. **Connectors > New Connector > MCP Server**
2. Enter the server URL (e.g., `https://mcp.linear.app/sse`)
3. Select transport: **SSE** or **Streamable HTTP**
4. Configure authentication if required (Bearer Token, Basic Auth, or OAuth2)
5. 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:
```typescript theme={null}
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:
```typescript theme={null}
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:
```typescript theme={null}
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:
```typescript main.ts theme={null}
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);
}
```
```typescript agent.ts theme={null}
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](https://mcp.run) or the [MCP servers directory](https://github.com/modelcontextprotocol/servers) 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 ` | 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
1. **MCP Gateway > New Gateway** — set name, select API Key
2. **Add Tools** — pick resources from any of your connectors
3. **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`:
```json theme={null}
{
"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
```bash theme={null}
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
```bash theme={null}
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
```bash theme={null}
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](https://github.com/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
Create REST, Database, and other connectors
Build custom tools for agents
Use MCP tools in agents
Track gateway calls and metrics