MCP integration

The Model Context Protocol (MCP) lets your agents connect to external services—Notion, GitHub, Slack, databases, APIs—with a single configuration block. Instead of building custom integrations for every service, MCP provides a standard interface agents already understand.

What is MCP?

Model Context Protocol is an open protocol for AI-tool integration. Services expose capabilities (like reading Notion pages or creating GitHub issues) through MCP servers, and agents consume them through a unified interface. Benefits:

One config, many services - Add any MCP-compatible service with JSON config
No code required - Agents discover tools automatically
Ecosystem growth - Hundreds of MCP servers already exist
Standard interface - Consistent behavior across all services

Quick start

Add an MCP server in three ways:

# Opens your editor with a template
jazz mcp add

MCP server configuration

stdio servers

Most MCP servers use stdio (stdin/stdout) transport:

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

HTTP servers

Some services use HTTP transport:

{
  "notion": {
    "transport": "http",
    "url": "https://mcp.notion.com/mcp",
    "headers": {
      "Authorization": "Bearer your_token_here"
    }
  }
}

Source: mcp.ts:14-28

Adding MCP servers

Add the server configuration

Run the add command:

jazz mcp add

Your editor opens with a template:

{
  "server-name": {
    "command": "your-command",
    "args": []
  }
}

Source: mcp.ts:106-184

Fill in the server details

Replace the template with actual server configuration:

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "ghp_your_token_here"
    }
  },
  "notion": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
  }
}

Save and close your editor

Jazz validates the configuration and adds the servers:

✓ Added MCP server: github
✓ Added MCP server: notion

Source: mcp.ts:36-79

Verify servers are available

List configured servers:

jazz mcp list

Output:

MCP Servers

  github (stdio: npx) [enabled]
  notion (stdio: npx) [enabled]

Source: mcp.ts:192-220

Using MCP tools in agents

When creating agents, MCP server tools appear as selectable categories:

jazz agent create

Which tools should this agent have access to?

  ◯ File Management (8 tools)
  ◯ Git (12 tools)
  ◯ HTTP (3 tools)
  ◯ Shell Commands (2 tools)
❯ ◉ GitHub (MCP) (15 tools)
  ◉ Notion (MCP) (8 tools)

The agent automatically discovers all tools from selected MCP servers. Source: create-agent.ts:132-142, 179-281

Managing MCP servers

List servers

jazz mcp list

Shows all configured servers with transport type and status:

MCP Servers

  github (stdio: npx) [enabled]
  notion (http) [enabled]
  slack (stdio: node) [disabled]

Remove a server

jazz mcp remove

Interactive selection:

Select a server to remove:
❯ github
  notion
  slack

Remove server "github"? (y/N)

Source: mcp.ts:228-281

Enable/disable servers

Disable a server without removing it:

jazz mcp disable

Re-enable later:

jazz mcp enable

Source: mcp.ts:288-357

Configuration storage

MCP configurations are stored in two places:

Server definitions: `~/.agents/mcp.json`

Full server configuration (command, args, environment):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Enable/disable overrides: `jazz.config.json`

Only stores enabled/disabled state:

{
  "mcpServers": {
    "github": { "enabled": true },
    "slack": { "enabled": false }
  }
}

This separation allows:

User-level definitions in ~/.agents/mcp.json (shared across projects)
Project-level overrides in jazz.config.json (disable servers for specific projects)

Source: config.ts:445-518

Popular MCP servers

GitHub

Manage repositories, issues, PRs:

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

Tools: create issues, comment on PRs, search code, manage branches

Notion

Read and write Notion pages:

{
  "notion": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
  }
}

Tools: read pages, create pages, update content, search

Slack

Send messages, read channels:

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-your-token"
    }
  }
}

Tools: post messages, list channels, read history

Database servers

PostgreSQL:

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@localhost/db"
    }
  }
}

SQLite:

{
  "sqlite": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/db.sqlite"]
  }
}

Authentication patterns

Environment variables

Most common for API tokens:

{
  "service": {
    "command": "npx",
    "args": ["-y", "mcp-server-name"],
    "env": {
      "API_KEY": "your-key-here",
      "API_SECRET": "your-secret"
    }
  }
}

Command arguments

For file paths or config:

{
  "service": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-server-name",
      "--token-file",
      "/path/to/token.txt"
    ]
  }
}

HTTP headers

For HTTP transport:

{
  "service": {
    "transport": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer your-token",
      "X-API-Key": "your-key"
    }
  }
}

Tool discovery

When an agent with MCP servers starts, Jazz:

Connects to each enabled server (45-second timeout)
Discovers available tools via MCP protocol
Registers tools in the agent’s tool registry
Makes tools available for agent use

If connection fails, Jazz logs a warning and continues without that server’s tools. Source: create-agent.ts:182-281

Examples

Email agent with Gmail MCP

# 1. Add Gmail MCP server
jazz mcp add --file gmail.json

# gmail.json
{
  "gmail": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-gmail"]
  }
}

# 2. Create agent with Gmail tools
jazz agent create
# Select Gmail (MCP) category

# 3. Use the agent
jazz agent chat email-assistant
> Summarize my unread emails from the last 24 hours

Notion knowledge base agent

# 1. Add Notion MCP server
jazz mcp add

{
  "notion": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
  }
}

# 2. Create agent
jazz agent create
# Select Notion (MCP) + File Management

# 3. Use for research
jazz agent chat research-bot
> Research GraphQL best practices and save findings to my Notion workspace

Multi-service automation

# 1. Add multiple MCP servers
jazz mcp add

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_TOKEN": "ghp_..." }
  },
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": { "SLACK_BOT_TOKEN": "xoxb-..." }
  }
}

# 2. Create workflow
cat > workflows/pr-notifications/WORKFLOW.md << 'EOF'
---
name: pr-notifications
schedule: "*/30 * * * *"  # Every 30 minutes
agent: automation-agent
autoApprove: low-risk
---

Check for new pull requests in my GitHub repos.
For each new PR, post a summary to #engineering on Slack.
EOF

# 3. Schedule it
jazz workflow schedule pr-notifications

Troubleshooting

Server tools not appearing

Verify the server is enabled:

jazz mcp list

If disabled, enable it:

jazz mcp enable

Connection timeout

MCP servers have a 45-second connection timeout. If a server takes longer:

⚠ MCP server GitHub connection timed out after 45 seconds

Possible causes:

Server requires manual authentication (OAuth flow)
Network issues
Server not installed or not in PATH

Solutions:

Check server documentation for auth requirements
Verify command and args are correct
Test server manually: npx -y @modelcontextprotocol/server-github

Source: create-agent.ts:213-243

Authentication required

Some servers need interactive authentication:

⚠ MCP server Notion requires authentication: OAuth flow needed

Follow the server’s authentication instructions, then try again.

Tool registration failed

If tools fail to register:

# Check agent configuration
jazz agent list

# Recreate agent with MCP category selected
jazz agent create

Advanced configuration

Project-specific MCP servers

Add servers to .agents/mcp.json in your project:

mkdir -p .agents
cat > .agents/mcp.json << 'EOF'
{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/myproject"
      }
    }
  }
}
EOF

Project servers merge with (and override) user-level servers. Source: config.ts:445-490

Disable servers per-project

In jazz.config.json:

{
  "mcpServers": {
    "github": { "enabled": false }
  }
}

Disables the GitHub server for this project only.

Custom MCP servers

Build your own MCP server for internal APIs:

{
  "internal-api": {
    "command": "node",
    "args": ["/path/to/your/mcp-server.js"],
    "env": {
      "API_BASE_URL": "https://internal.company.com/api",
      "API_TOKEN": "your-token"
    }
  }
}

See MCP documentation for server development.

Best practices

Store credentials securely - Use environment variables, not hardcoded tokens in config files.

Test servers individually - Run npx -y server-name to verify it works before adding to Jazz.

Use project-specific servers - Keep project-related MCP servers in .agents/mcp.json for portability.

Limit server access - Only enable MCP servers agents actually need. Disable unused servers.

Review tool permissions - MCP servers can expose powerful capabilities. Understand what each tool does.

Next steps

Configuration - Customize MCP server behavior
Workflows - Automate tasks using MCP-connected agents
Creating agents - Build agents with MCP tool access

Get Started

Core Concepts

Guides

Use Cases

Documentation Index

​What is MCP?

​Quick start

​MCP server configuration

​stdio servers

​HTTP servers

​Adding MCP servers

​Using MCP tools in agents

​Managing MCP servers

​List servers

​Remove a server

​Enable/disable servers

​Configuration storage

​Server definitions: ~/.agents/mcp.json

​Enable/disable overrides: jazz.config.json

​Popular MCP servers

​GitHub

​Notion

​Slack

​Database servers

​Authentication patterns

​Environment variables

​Command arguments

​HTTP headers

​Tool discovery

​Examples

​Email agent with Gmail MCP

​Notion knowledge base agent

​Multi-service automation

​Troubleshooting

​Server tools not appearing

​Connection timeout

​Authentication required

​Tool registration failed

​Advanced configuration

​Project-specific MCP servers

​Disable servers per-project

​Custom MCP servers

​Best practices

​Next steps

Build docs developers (and LLMs) love

What is MCP?

Quick start

MCP server configuration

stdio servers

HTTP servers

Adding MCP servers

Using MCP tools in agents

Managing MCP servers

List servers

Remove a server

Enable/disable servers

Configuration storage

Server definitions: `~/.agents/mcp.json`

Enable/disable overrides: `jazz.config.json`

Popular MCP servers

GitHub

Notion

Slack

Database servers

Authentication patterns

Environment variables

Command arguments

HTTP headers

Tool discovery

Examples

Email agent with Gmail MCP

Notion knowledge base agent

Multi-service automation

Troubleshooting

Server tools not appearing

Connection timeout

Authentication required

Tool registration failed

Advanced configuration

Project-specific MCP servers

Disable servers per-project

Custom MCP servers

Best practices

Next steps