MCP (Model Context Protocol)

What is MCP?

Model Context Protocol (MCP) is an open standard for connecting AI agents to external services. It’s like a universal adapter that lets your agents talk to databases, APIs, third-party services, and custom tools. With MCP, you can:

Connect to databases: Postgres, SQLite, MongoDB
Integrate services: Notion, GitHub, Slack, Google Drive
Access APIs: Any REST API, GraphQL endpoint
Build custom tools: Expose your own services to agents

MCP is an open standard developed by Anthropic and supported by the AI community. Any MCP-compatible tool works with Jazz.

Why MCP matters

Without MCP, integrating each service requires:

Custom tool implementation
API client code
Authentication handling
Error handling
Maintenance as APIs change

With MCP:

One config block → instant integration
Community tools → reuse existing servers
Standard protocol → consistent behavior
Automatic updates → servers handle API changes

How MCP works

Agent decides to use an MCP tool (e.g., “search Notion”)
MCP Client (in Jazz) sends request via MCP protocol
MCP Server receives request and calls the external service
External Service returns data
MCP Server formats response
Agent receives structured result

Transport types

Jazz supports two MCP transport mechanisms:

Stdio transport

Runs MCP servers as local processes:

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

Use for: Local tools, npm packages, custom scripts
Pros: Easy setup, runs locally
Cons: Requires Node.js/npm/npx

HTTP transport

Connects to remote MCP servers via HTTP:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${NOTION_TOKEN}"
      }
    }
  }
}

Use for: Cloud services, hosted tools, remote APIs
Pros: No local dependencies, scales easily
Cons: Requires network access

Adding MCP servers

Interactive setup

jazz mcp add

You’ll be prompted for:

Server name
Transport type (stdio or HTTP)
Command/URL
Environment variables or headers

Manual configuration

Edit ~/.jazz/config.json:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${NOTION_TOKEN}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

Use ${VAR_NAME} for environment variables. Jazz will resolve them from your shell environment.

List configured servers

jazz mcp list

Shows all configured MCP servers and their status.

Using MCP tools

Once configured, MCP tools appear in the agent’s tool list automatically:

jazz
> Search my Notion workspace for "project roadmap"

# Agent sees notion_search tool from MCP server
# Calls the tool
# Returns results from Notion

Agents discover and use MCP tools like any other tool—no special syntax required.

List available MCP tools

During a conversation:

/tools

This shows all tools, including those from MCP servers.

MCP server implementation

From src/services/mcp/mcp-server-manager.ts, here’s how Jazz manages MCP connections:

Connection management

// Connect to an MCP server
connectServer(config: MCPServerConfig): Effect.Effect<MCPClient, MCPConnectionError> {
  // Create transport (stdio or HTTP)
  // Connect with retry logic
  // Return client
}

// Get tools from a connected server
getServerTools(serverName: string): Effect.Effect<MCPTool[], MCPToolDiscoveryError> {
  // Query server for available tools
  // Normalize tool definitions
  // Return tools
}

// Disconnect when done
disconnectServer(serverName: string): Effect.Effect<void, MCPDisconnectionError> {
  // Close client connection
  // Clean up resources
}

Lazy connection

MCP servers connect only when needed:

// From agent-runner.ts:89-99
// Register MCP tools for this agent if needed (only connects to relevant servers)
const connectedMCPServers = yield* registerMCPToolsForAgent(agentToolNames).pipe(
  Effect.catchAll((error) =>
    Effect.gen(function* () {
      const logger = yield* LoggerServiceTag;
      yield* logger.warn(`Failed to register MCP tools: ${error.message}`);
      // Continue even if MCP registration fails - tools might not be needed
      return [];
    }),
  ),
);

This prevents:

Slow startup (servers connect on-demand)
Hanging processes (only connects when agent needs the tools)
Resource waste (doesn’t connect to unused servers)

Retry logic

// From mcp-server-manager.ts:109-136
const client = yield* retryWithBackoff(connectEffect, {
  maxRetries: 3,
  initialDelayMs: 1000,
  maxDelayMs: 10_000,
  shouldRetry: (error: unknown) => {
    const errorMessage = error instanceof Error ? error.message : String(error);
    return (
      errorMessage.includes("ECONNREFUSED") ||
      errorMessage.includes("ETIMEDOUT") ||
      errorMessage.includes("timeout") ||
      errorMessage.includes("connection")
    );
  },
});

MCP connections retry on transient failures (network issues, timeouts) but fail fast on configuration errors.

Popular MCP servers

Official servers

Server	Purpose	Install
`@modelcontextprotocol/server-github`	GitHub repos, issues, PRs	`npx -y @modelcontextprotocol/server-github`
`@modelcontextprotocol/server-postgres`	Postgres database access	`npx -y @modelcontextprotocol/server-postgres`
`@modelcontextprotocol/server-sqlite`	SQLite database access	`npx -y @modelcontextprotocol/server-sqlite`
`@modelcontextprotocol/server-filesystem`	Enhanced file operations	`npx -y @modelcontextprotocol/server-filesystem`
`@modelcontextprotocol/server-google-drive`	Google Drive integration	`npx -y @modelcontextprotocol/server-google-drive`

Community servers

Server	Purpose	More Info
Notion	Notion workspace access	mcp.notion.com
Slack	Slack channel integration	MCP Slack Server
MongoDB	MongoDB database access	Community MCP Servers
Airtable	Airtable base integration	MCP Airtable Server

Browse the MCP Servers Registry for the full list of community servers.

Configuration examples

GitHub integration

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

Setup:

Create a GitHub Personal Access Token
Export: export GITHUB_TOKEN=ghp_...
Add config to ~/.jazz/config.json

Usage:

jazz
> List all open issues in my repo with "bug" label
> Create a new issue titled "Fix login error" in myuser/myrepo

Notion integration

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${NOTION_TOKEN}"
      }
    }
  }
}

Setup:

Get API key from Notion Integrations
Share pages/databases with your integration
Export: export NOTION_TOKEN=secret_...
Add config to ~/.jazz/config.json

Usage:

jazz
> Search my Notion workspace for "meeting notes from last week"
> Create a new page in my Projects database

Postgres database

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Usage:

jazz
> Show me all users who signed up in the last 7 days
> Count total orders by status
> Create a new table for storing analytics events

Be cautious with database access. Agents can execute any SQL query. Use read-only credentials when possible.

Multiple servers

Configure multiple services:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${NOTION_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Agents can use tools from all configured servers in a single conversation:

jazz
> Check GitHub for recent issues, search Notion for related docs, then query Postgres for usage stats

Building custom MCP servers

Create your own MCP server to expose custom services:

Basic server structure

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Create server
const server = new Server(
  {
    name: "my-custom-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Register tools
server.setRequestHandler("tools/list", async () => {
  return {
    tools: [
      {
        name: "my_custom_tool",
        description: "Does something useful",
        inputSchema: {
          type: "object",
          properties: {
            query: {
              type: "string",
              description: "The query parameter",
            },
          },
          required: ["query"],
        },
      },
    ],
  };
});

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "my_custom_tool") {
    const result = await doSomething(request.params.arguments.query);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result),
        },
      ],
    };
  }
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Add to Jazz

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"]
    }
  }
}

See MCP SDK Documentation for complete server development guides.

Security considerations

Credential management

Use environment variables: Don’t hardcode secrets in config
Rotate tokens: Regularly update API keys and tokens
Minimal permissions: Use read-only credentials when possible
Audit access: Review what tools agents can access

Connection security

HTTPS only: Use secure URLs for HTTP transport
Verify certificates: Don’t disable SSL verification
Network isolation: Run sensitive MCP servers in isolated environments
Rate limiting: Monitor and limit API calls

Tool access control

Limit which agents can use MCP tools:

// Agent configuration
{
  "tools": ["github", "notion"]  // Only these MCP servers
}

Or use specific tool names:

{
  "tools": ["github_list_issues", "notion_search"]  // Specific tools only
}

Troubleshooting

Server won’t connect

Check command: Verify the command/path exists

npx -y @modelcontextprotocol/server-github

Check environment variables: Ensure they’re exported
```
echo $GITHUB_TOKEN
```
Check logs: Run Jazz with debug output
```
DEBUG=* jazz
```

Test server directly: Run the MCP server standalone

GITHUB_TOKEN=... npx -y @modelcontextprotocol/server-github

Tools not appearing

List MCP servers: Verify server is configured
```
jazz mcp list
```

Check agent tools: Ensure agent has access

# In config: "tools": ["all"] or "tools": ["github"]

Refresh tools: Restart Jazz to re-discover tools

Connection errors

Timeout: Increase retry settings or check network
Auth failed: Verify API keys and tokens
Command not found: Check npx is installed and in PATH
Port conflicts: Ensure no other process uses the MCP port

MCP server manager API

For programmatic access:

import { MCPServerManagerTag } from "@/core/interfaces/mcp-server";

// Connect to server
const client = yield* MCPServerManagerTag.pipe(
  Effect.flatMap((manager) => manager.connectServer(config))
);

// Get tools from server
const tools = yield* MCPServerManagerTag.pipe(
  Effect.flatMap((manager) => manager.getServerTools("github"))
);

// Disconnect
yield* MCPServerManagerTag.pipe(
  Effect.flatMap((manager) => manager.disconnectServer("github"))
);

// List all configured servers
const servers = yield* MCPServerManagerTag.pipe(
  Effect.flatMap((manager) => manager.listServers())
);

// Disconnect all
yield* MCPServerManagerTag.pipe(
  Effect.flatMap((manager) => manager.disconnectAllServers())
);

Best practices

Start small

Begin with one MCP server:

{
  "mcpServers": {
    "github": { /* config */ }
  }
}

Verify it works before adding more.

Document credentials

Maintain a README with required environment variables:

# Required Environment Variables

- `GITHUB_TOKEN`: GitHub personal access token (repo scope)
- `NOTION_TOKEN`: Notion integration token
- `DATABASE_URL`: Postgres connection string

Use tool allowlists

Create agents with specific MCP access:

# Research agent - only needs web access
jazz agent create researcher --tools web-search,http-request

# Data agent - needs database access
jazz agent create data-analyst --tools postgres

# Integration agent - needs multiple services
jazz agent create integrations --tools github,notion,slack

Monitor usage

Track which MCP tools are used:

Review agent logs
Monitor API usage in external services
Set up rate limiting

Next steps

Agents

Configure agents to use MCP tools

Tools

Explore built-in and MCP tools

MCP SDK

Build custom MCP servers

MCP Registry

Browse community MCP servers

Get Started

Core Concepts

Guides

Use Cases

Documentation Index

​What is MCP?

​Why MCP matters

​How MCP works

​Transport types

​Stdio transport

​HTTP transport

​Adding MCP servers

​Interactive setup

​Manual configuration

​List configured servers

​Using MCP tools

​List available MCP tools

​MCP server implementation

​Connection management

​Lazy connection

​Retry logic

​Popular MCP servers

​Official servers

​Community servers

​Configuration examples

​GitHub integration

​Notion integration

​Postgres database

​Multiple servers

​Building custom MCP servers

​Basic server structure

​Add to Jazz

​Security considerations

​Credential management

​Connection security

​Tool access control

​Troubleshooting

​Server won’t connect

​Tools not appearing

​Connection errors

​MCP server manager API

​Best practices

​Start small

​Document credentials

​Use tool allowlists

​Monitor usage

​Next steps

Agents

Tools

MCP SDK

MCP Registry

Build docs developers (and LLMs) love

What is MCP?

Why MCP matters

How MCP works

Transport types

Stdio transport

HTTP transport

Adding MCP servers

Interactive setup

Manual configuration

List configured servers

Using MCP tools

List available MCP tools

MCP server implementation

Connection management

Lazy connection

Retry logic

Popular MCP servers

Official servers

Community servers

Configuration examples

GitHub integration

Notion integration

Postgres database

Multiple servers

Building custom MCP servers

Basic server structure

Add to Jazz

Security considerations

Credential management

Connection security

Tool access control

Troubleshooting

Server won’t connect

Tools not appearing

Connection errors

MCP server manager API

Best practices

Start small

Document credentials

Use tool allowlists

Monitor usage

Next steps