MCP servers

MCP servers are tool surfaces. They speak the Model Context Protocol, which means any MCP-compliant tool can be wired into a workflow node without writing a custom adapter. GitHub, Linear, Postgres, a custom internal tool, anything that has an MCP shim.

Attach an MCP server to a node and that node can call the tools the server exposes. Skip the field and the node has no MCP tools available. Tools are per-node, not per-workflow, so you don't over-provision.

The MCP attachment works on Claude nodes. Codex nodes will warn and ignore the mcp field; the Codex SDK uses a different tool integration model.

Quick Start

Create an MCP config file (e.g., .zen/mcp/github.json):

json

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
    }
  }
}

Reference it in your workflow:

yaml

name: triage-issues
description: Triage GitHub issues using MCP
nodes:
  - id: triage
    prompt: "List open issues and label them by priority"
    mcp: .zen/mcp/github.json

That's it. The MCP server starts when the node runs, its tools become available to the AI, and it shuts down when the node completes.

Config File Format

MCP config files are JSON objects where each key is a server name and the value is a server configuration. Three transport types are supported:

stdio (default)

Runs a local process. This is the most common type.

json

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
    }
  }
}

Field	Type	Required	Description
`type`	`'stdio'`	No	Default when omitted
`command`	string	Yes	Executable to run
`args`	string[]	No	Command arguments
`env`	Record<string, string>	No	Environment variables for the process

HTTP

Connects to a remote HTTP endpoint.

json

{
  "api": {
    "type": "http",
    "url": "https://mcp.example.com/v1",
    "headers": {
      "Authorization": "Bearer $API_KEY"
    }
  }
}

Field	Type	Required	Description
`type`	`'http'`	Yes	Must be `'http'`
`url`	string	Yes	HTTP endpoint URL
`headers`	Record<string, string>	No	Request headers

SSE (Server-Sent Events)

Connects to an SSE endpoint.

json

{
  "realtime": {
    "type": "sse",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "Authorization": "Bearer $SSE_TOKEN"
    }
  }
}

Field	Type	Required	Description
`type`	`'sse'`	Yes	Must be `'sse'`
`url`	string	Yes	SSE endpoint URL
`headers`	Record<string, string>	No	Request headers

Environment Variable Expansion

Values in env and headers fields support $VAR_NAME references that are expanded from process.env at execution time.

json

{
  "db": {
    "command": "npx",
    "args": ["-y", "@mcp/server-postgres"],
    "env": {
      "DATABASE_URL": "$DATABASE_URL",
      "POOL_SIZE": "$DB_POOL_SIZE"
    }
  }
}

Rules:

Pattern: $UPPER_CASE_VAR (matches [A-Z_][A-Z0-9_]*)
Only env and headers values are expanded; command, args, url are left untouched
Undefined vars are replaced with empty string and a warning is shown: Warning: Node 'X' MCP config references undefined env vars: VAR_NAME
Expansion happens at execution time, not when the workflow YAML is loaded

Why file-based? MCP configs often contain secrets (API tokens, database URLs). Workflow YAML files are committed to git. By keeping configs in separate JSON files, you can gitignore them or rely on env var references so secrets never appear in source.

Multiple Servers Per Node

A single config file can define multiple servers:

json

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN" }
  },
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": { "DATABASE_URL": "$DATABASE_URL" }
  }
}

Automatic Tool Wildcards

When a node loads MCP servers, tool wildcards are automatically added to allowedTools. For servers named github and postgres, the node gets:

mcp__github__*
mcp__postgres__*

This means all tools from those servers are immediately available without manually listing them. The wildcards merge with any existing allowed_tools on the node.

MCP-Only Nodes

Combine mcp with allowed_tools: [] to create nodes that can only use MCP tools and have no access to built-in tools (Bash, Read, Write, etc.):

yaml

nodes:
  - id: query-db
    prompt: "Find all users who signed up in the last 24 hours"
    mcp: .zen/mcp/postgres.json
    allowed_tools: []

This is useful for sandboxing; the AI can only interact through the MCP server and cannot touch the filesystem or run shell commands.

Connection Failure Handling

MCP server connections are established when the node starts executing. If a server fails to connect, you'll see a message like:

MCP server connection failed: github (failed)

The node continues executing but without the tools from the failed server. Check your config file path, server command, and environment variables if this happens.

Workflow Examples

GitHub Issue Triage

yaml

name: triage-issues
description: Fetch and label GitHub issues
nodes:
  - id: triage
    prompt: |
      List all open issues in this repo.
      For each issue, add a priority label (P0-P3) based on:
      - P0: Security vulnerabilities, data loss
      - P1: Broken core functionality
      - P2: Important but not blocking
      - P3: Nice to have
    mcp: .zen/mcp/github.json

Database-Informed Code Changes

yaml

name: schema-aware-feature
description: Build features with live database context
nodes:
  - id: inspect-schema
    prompt: "List all tables and their columns in the database"
    mcp: .zen/mcp/postgres.json
    allowed_tools: []

  - id: implement
    command: implement-feature
    depends_on: [inspect-schema]

Multi-Service Orchestration

yaml

name: full-stack-fix
description: Fix a bug using GitHub issues, database, and code
nodes:
  - id: fetch-context
    prompt: "Get issue details and related database schema"
    mcp: .zen/mcp/all-services.json
    allowed_tools: []

  - id: fix
    command: implement-fix
    depends_on: [fetch-context]

  - id: verify
    prompt: "Run the relevant query to verify the fix"
    depends_on: [fix]
    mcp: .zen/mcp/postgres.json
    allowed_tools: []

Read-Only Analysis with Hooks

Combine MCP with hooks to create nodes that can query external services but cannot modify the codebase:

yaml

nodes:
  - id: analyze
    prompt: "Analyze our GitHub PR review patterns"
    mcp: .zen/mcp/github.json
    hooks:
      PreToolUse:
        - matcher: "Write|Edit|Bash"
          response:
            hookSpecificOutput:
              hookEventName: PreToolUse
              permissionDecision: deny
              permissionDecisionReason: "Analysis only; no code changes"

Push Notifications (ntfy)

Some built-in workflows (like zen-piv-loop) include an optional notification node that sends a push notification to your phone when the workflow completes. It's gated behind a when: condition; if you haven't configured ntfy, the node is silently skipped.

Setup (30 seconds)

Install the ntfy app on your phone (iOS / Android)
Open the app, tap "+", subscribe to a topic name (e.g. zen-yourname-a8f3x). Treat the topic name like a password; anyone who knows it can send you notifications.
Create .zen/mcp/ntfy.json in your repo:

json

{
  "ntfy": {
    "command": "npx",
    "args": ["-y", "ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "zen-yourname-a8f3x"
    }
  }
}

That's it. The file is gitignored (.zen/mcp/ is in .gitignore), so your topic stays local.

How it works in workflows

Workflows use a bash node to check if the config file exists:

yaml

  - id: check-ntfy
    bash: "test -f .zen/mcp/ntfy.json && echo 'true' || echo 'false'"
    depends_on: [last-work-node]

  - id: notify
    depends_on: [check-ntfy, last-work-node]
    when: "$check-ntfy.output == 'true'"
    mcp: .zen/mcp/ntfy.json
    allowed_tools: []
    prompt: |
      Send a push notification summarizing what was accomplished.
      Keep it under 2 sentences. Use priority 3.

If .zen/mcp/ntfy.json doesn't exist, check-ntfy outputs false, the when: condition skips the notify node, and the workflow runs exactly as before.

Adding notifications to your own workflows

Add the two nodes above (check-ntfy + notify) to the end of any DAG workflow. The notify node's prompt should reference upstream node outputs (e.g. $synthesize.output) to generate a meaningful summary.

Quick test

bash

# Verify your phone receives notifications
curl -d "Hello from Z.E.N." ntfy.sh/YOUR_TOPIC_NAME

# Run a workflow with notifications
bun run cli workflow run zen-piv-loop "Review PR #123"

MCP vs allowed_tools/denied_tools vs hooks

Feature	`mcp`	`allowed_tools`/`denied_tools`	`hooks`
Add external tools	Yes	No	No
Remove built-in tools	No	Yes	Yes
Inject context	No	No	Yes
Modify tool input	No	No	Yes
Sandbox to MCP only	`mcp` + `allowed_tools: []`	;	;

Limitations

Claude only; Codex nodes warn and ignore the mcp field. Configure MCP servers globally in the Codex CLI config instead.
Haiku model; Tool search (lazy loading for many tools) is not supported on Haiku. You'll see a warning. Consider using Sonnet or Opus for MCP nodes.
No load-time validation; The MCP config file is read at execution time, not when the workflow YAML is loaded. A typo in the path won't surface until the node runs.
No inline config; MCP configs must be in a separate JSON file, not inline in YAML. This is intentional; it keeps secrets out of version-controlled workflow files.

Troubleshooting

Problem	Cause	Fix
`MCP config file not found`	Wrong path or file doesn't exist	Check the path relative to your repo root (cwd)
`MCP config file is not valid JSON`	Syntax error in JSON	Validate with `cat .zen/mcp/config.json \| python3 -m json.tool`
`MCP config must be a JSON object`	Top-level value is array or string	Wrap in `{ "server-name": { ... } }`
`undefined env vars: VAR_NAME`	Environment variable not set	Export the variable or add it to your `.env`
`MCP server connection failed`	Server process crashed or URL unreachable	Check command/URL, test the server standalone
`mcp config but uses Codex`	Node resolved to Codex provider	Set `provider: claude` on the node or switch default
`Haiku model with MCP servers`	Haiku doesn't support tool search	Use `model: sonnet` or `model: opus` instead

Finding MCP Servers

Popular MCP servers for common integrations:

GitHub: @modelcontextprotocol/server-github
PostgreSQL: @modelcontextprotocol/server-postgres
Filesystem: @modelcontextprotocol/server-filesystem
Slack: @modelcontextprotocol/server-slack
Google Drive: @modelcontextprotocol/server-gdrive
Brave Search: @modelcontextprotocol/server-brave-search

Browse the full directory at modelcontextprotocol.io/servers.

MCP servers ​

Quick Start ​

Config File Format ​

stdio (default) ​

HTTP ​

SSE (Server-Sent Events) ​

Environment Variable Expansion ​

Multiple Servers Per Node ​

Automatic Tool Wildcards ​

MCP-Only Nodes ​

Connection Failure Handling ​

Workflow Examples ​

GitHub Issue Triage ​

Database-Informed Code Changes ​

Multi-Service Orchestration ​

Read-Only Analysis with Hooks ​

Push Notifications (ntfy) ​

Setup (30 seconds) ​

How it works in workflows ​

Adding notifications to your own workflows ​

Quick test ​

MCP vs allowed_tools/denied_tools vs hooks ​

Limitations ​

Troubleshooting ​

Finding MCP Servers ​

MCP servers

Quick Start

Config File Format

stdio (default)

HTTP

SSE (Server-Sent Events)

Environment Variable Expansion

Multiple Servers Per Node

Automatic Tool Wildcards

MCP-Only Nodes

Connection Failure Handling

Workflow Examples

GitHub Issue Triage

Database-Informed Code Changes

Multi-Service Orchestration

Read-Only Analysis with Hooks

Push Notifications (ntfy)

Setup (30 seconds)

How it works in workflows

Adding notifications to your own workflows

Quick test

MCP vs allowed_tools/denied_tools vs hooks

Limitations

Troubleshooting

Finding MCP Servers