zag-cli 0.12.6

# zag mcp

Manage MCP (Model Context Protocol) servers across providers.

## Synopsis

    zag mcp <command> [options]

## Description

MCP servers extend agent capabilities with external tools and data sources via the Model Context Protocol. Zag stores MCP server configurations as individual TOML files and syncs them into each provider's native config format.

Servers are stored at:
- **Global**: `~/.zag/mcp/<server-name>.toml`
- **Project-scoped**: `~/.zag/projects/<sanitized-path>/mcp/<server-name>.toml`

Project-scoped servers override global servers with the same name.

## Server Format

Each server is a single TOML file:

```toml
# ~/.zag/mcp/github.toml
name = "github"
description = "GitHub MCP server"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[env]
GITHUB_TOKEN = "${GITHUB_TOKEN}"
```

HTTP transport example:

```toml
# ~/.zag/mcp/sentry.toml
name = "sentry"
transport = "http"
url = "https://mcp.sentry.dev/sse"
bearer_token_env_var = "SENTRY_AUTH_TOKEN"
```

## Provider Integration

During sync, servers are injected with a `zag-` prefix into each provider's native config. User-managed entries are never modified.

| Provider | Config File | Format |
|----------|-----------|--------|
| Claude   | `~/.claude.json` | JSON `mcpServers` |
| Gemini   | `~/.gemini/settings.json` | JSON `mcpServers` |
| Copilot  | `~/.copilot/mcp-config.json` | JSON `mcpServers` |
| Codex    | `~/.codex/config.toml` | TOML `[mcp_servers]` |
| Ollama   | N/A | Not supported |

## Commands

### list

List all configured MCP servers (global + project-scoped).

    zag mcp list [--json] [-r root]

### show

Show details of a specific MCP server.

    zag mcp show <name> [--json] [-r root]

### add

Add a new MCP server configuration.

    zag mcp add <name> [options]

Options:
- `--transport` — Transport type: `stdio` or `http` (default: stdio)
- `--command` — Command to start the server (stdio)
- `--args` — Arguments for the command
- `--url` — URL endpoint (http)
- `--env KEY=VALUE` — Environment variables (repeatable)
- `--description` — Short description
- `--global` — Store in global directory (`~/.zag/mcp/`) instead of project-scoped

### remove

Remove an MCP server and clean up all provider configs.

    zag mcp remove <name>

### sync

Sync MCP servers to all provider-specific configs. Runs automatically before each agent session.

    zag mcp sync [-p provider]

Options:
- `-p, --provider` — Only sync for this provider (claude, gemini, copilot, codex)

### import

Import MCP servers from a provider's native config into `~/.zag/mcp/`.

    zag mcp import [--from <provider>]

Options:
- `--from` — Provider to import from (default: claude). Skips entries prefixed with `zag-`.

## Examples

    # Add a stdio MCP server
    zag mcp add github --command npx --args -y @modelcontextprotocol/server-github

    # Add with environment variables
    zag mcp add github --command npx --args -y @modelcontextprotocol/server-github --env GITHUB_TOKEN='${GITHUB_TOKEN}'

    # Add an HTTP MCP server
    zag mcp add sentry --transport http --url https://mcp.sentry.dev/sse

    # Add a global server
    zag mcp add my-db --command npx --args -y db-mcp --global

    # List all servers
    zag mcp list

    # List as JSON
    zag mcp list --json

    # Show a specific server
    zag mcp show github

    # Manually sync to all providers
    zag mcp sync

    # Only sync to Claude
    zag mcp sync -p claude

    # Import your existing Claude MCP servers
    zag mcp import --from claude

    # Import from Codex
    zag mcp import --from codex

    # Remove a server
    zag mcp remove github

## See Also

    zag man zag       Global flags and providers overview
    zag man skills    Manage provider-agnostic skills
    zag man run       Start an interactive session (MCP servers are synced automatically)