MCP Servers

How to connect an agent to an external service.

Jazz speaks Model Context Protocol. Add a server with jazz mcp add, then include its tools in an agent’s tool list.

Servers connect lazily. Jazz does not connect at startup — a server is launched the first time one of its tools is actually invoked, so a broken or slow server never blocks jazz from starting. See Design decisions.

Schemas load lazily too. Once connected, a server’s tools appear in the agent’s prompt by name and one-line summary only — the model fetches a tool’s full schema via search_tools the first time it needs one. See Design decisions.

Jazz supports Model Context Protocol (MCP) servers, allowing your agents to connect to external tools and services. MCP is an open standard that enables AI assistants to interact with various data sources and APIs.

What is MCP?

MCP (Model Context Protocol) provides a standardized way for AI agents to:

Access external tools: Connect to databases, APIs, and services
Use custom capabilities: Extend agents with domain-specific functionality
Maintain context: Share information across tool calls

Configuration

A server’s full definition — command, args, env — only ever lives in .agents/mcp.json. jazz mcp add writes there for you; if you’re editing by hand, that’s the file to edit:

// ~/.agents/mcp.json (user-level) or ./.agents/mcp.json (project-level, in your repo root)
{
  "mcpServers": {
    "serverName": {
      "command": "npx",
      "args": ["-y", "package-name", "additional-args"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Both locations merge, following the .agents convention — project overrides user on a name collision.

~/.jazz/config.json (and its project-local ./.jazz/config.json override) can also declare mcpServers, but only to toggle enabled/trusted on a server already defined above — a command/args/env written here is silently ignored, not merged in:

// ~/.jazz/config.json
{
  "mcpServers": {
    "serverName": { "enabled": false }
  }
}

If a tool you expect isn’t showing up, check that the server itself is actually declared in .agents/mcp.json, not just referenced from ~/.jazz/config.json.

Configuration Options

Field	Type	Required	Description
`command`	`string`	Yes	The command to start the MCP server
`args`	`string[]`	No	Command line arguments
`env`	`object`	No	Environment variables passed to the server

Assigning MCP Servers to Agents

When creating or editing an agent, you can assign MCP server tools:

jazz agent create
# During creation, select MCP tools from the available servers

Or configure directly in your agent’s config:

{
  "agents": {
    "my-agent": {
      "tools": ["Notionmcp", "Mongodb"]
    }
  }
}

Note: Tool names are case-insensitive and derived from the server name (e.g., notionMCP → Notionmcp).

Popular MCP Servers

Notion

Connect to your Notion workspace to search, read, and manage pages.

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

Available Tools:

notion-search - Search pages and databases
notion-fetch - Get page content
notion-create-pages - Create new pages
notion-update-page - Update existing pages
notion-create-database - Create databases
And more…

Setup: Authentication is handled via the Notion MCP remote server. The first time you use it, you’ll be prompted to authorize access to your Notion workspace.

MongoDB

Query and manage MongoDB databases directly from your agents.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-mongodb"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017"
      }
    }
  }
}

Available Tools:

find - Query documents
aggregate - Run aggregation pipelines
count - Count documents
list-collections - List all collections
list-databases - List all databases
collection-schema - Get collection schema
And more…

PostgreSQL

Connect to PostgreSQL databases for SQL queries. The server accepts the connection string as a command-line argument.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/dbname"]
    }
  }
}

Available Tools:

query - Execute SQL queries
list-tables - List database tables
describe-table - Get table schema

GitHub

Access GitHub repositories, issues, and pull requests.

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

Setup:

Create a GitHub Personal Access Token
Grant necessary permissions (repo, read:user, etc.)
Add the token to your config

Available Tools:

Search repositories, issues, PRs
Read file contents
Create/update issues
Manage pull requests

Slack

Send messages and interact with Slack workspaces.

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-...",
        "SLACK_TEAM_ID": "T..."
      }
    }
  }
}

Setup:

Create a Slack App
Add necessary OAuth scopes
Install to your workspace
Copy the Bot Token

Filesystem

Access and manage local files.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    }
  }
}

Security: Only files within the specified directory can be accessed.

Custom HTTP MCP Servers

For MCP servers running over HTTP (Streamable HTTP transport):

{
  "mcpServers": {
    "my-http-server": {
      "url": "https://my-mcp-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Finding More MCP Servers

Official Registry: modelcontextprotocol.io/servers
GitHub: Search for mcp-server- prefixed packages
npm: Search for @modelcontextprotocol/server-

Troubleshooting

“Invalid arguments” Error:

The MCP server requires specific arguments that weren’t provided
Check the server’s documentation for required parameters
Verify your agent is passing the correct arguments

“Tool not found” Error:

Ensure the MCP server is configured in ~/.jazz/config.json or ./.jazz/config.json
Verify the server name matches the agent’s tool configuration
Check that the server starts successfully (check logs)

Connection Errors:

Verify the command and args are correct
Check that required packages are installed (npx -y should auto-install)
Review environment variables for missing credentials

Authentication Errors:

Verify API keys/tokens are correct
Check that credentials have necessary permissions
Some servers require manual authorization flow

Integrations index
Configuration — the full config file reference
LLM Providers

MCP Servers

What is MCP?

Configuration

Configuration Options

Assigning MCP Servers to Agents

Popular MCP Servers

Notion

MongoDB

PostgreSQL

GitHub

Slack

Filesystem

Custom HTTP MCP Servers

Finding More MCP Servers

Troubleshooting

Related