# Multi-Agent MCP Installation

## Contents

- [Overview](#overview)
- [Source Types](#source-types)
- [Agent Configuration Reference](#agent-configuration-reference)
- [Config Format Examples](#config-format-examples)
- [Agent-Specific Transformations](#agent-specific-transformations)
- [Manual Multi-Agent Setup](#manual-multi-agent-setup)

## Overview

[add-mcp](https://github.com/neondatabase/add-mcp) is a CLI tool that installs MCP servers into multiple coding agents with a single command. It handles agent detection, config format differences, and agent-specific transformations automatically.

```bash
npx add-mcp <source> [options]
```

**Source types detected automatically:**
- URLs (`https://...`) → Remote HTTP/SSE server
- npm packages (`@org/package` or `package-name`) → Stdio via `npx -y`
- Commands with spaces (`npx -y @org/server --flag`) → Stdio with custom args

**Name inference:** Server names are auto-inferred from the source:
- `https://mcp.neon.tech/mcp` → `neon`
- `@modelcontextprotocol/server-postgres` → `postgres`
- `mcp-server-github` → `github`

Use `-n <name>` to override.

## Source Types

### Remote (HTTP/SSE)

```bash
# HTTP (default)
npx add-mcp https://mcp.stripe.com

# SSE (deprecated, use HTTP when possible)
npx add-mcp https://mcp.example.com/sse --transport sse

# With auth headers
npx add-mcp --header "Authorization: Bearer TOKEN" https://api.example.com/mcp
```

### npm Packages

```bash
# Scoped package
npx add-mcp @modelcontextprotocol/server-postgres

# Simple package
npx add-mcp mcp-server-github
```

Installed via `npx -y <package>` as stdio transport.

### Local Commands

```bash
# Custom npx command with args
npx add-mcp "npx -y @org/mcp-server --config /path/to/config"

# Node script
npx add-mcp "node /path/to/server.js --port 3000"

# Python server
npx add-mcp "python -m mcp_server --host localhost"
```

## Agent Configuration Reference

### Claude Code

| Property | Value |
|----------|-------|
| Global config | `~/.claude.json` |
| Project config | `.mcp.json` |
| Config key | `mcpServers` |
| Format | JSON |
| Transports | stdio, http (Streamable HTTP, recommended); sse (legacy, end-of-life April 2026) |
| OAuth | OAuth 2.1, RFC 9728 PRM discovery, CIMD/SEP-991 |
| Large output | `_meta["anthropic/maxResultSizeChars"]` up to 500K |
| Plugin MCP | servers from enabled plugins auto-connect; `/reload-plugins` to re-init |

### Claude Desktop

| Property | Value |
|----------|-------|
| Global config (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Global config (Windows) | `%APPDATA%/Claude/claude_desktop_config.json` |
| Global config (Linux) | `~/.config/Claude/claude_desktop_config.json` |
| Project config | Not supported (global only) |
| Config key | `mcpServers` |
| Format | JSON |
| Transports | stdio, http, sse |

### Cursor

| Property | Value |
|----------|-------|
| Global config | `~/.cursor/mcp.json` |
| Project config | `.cursor/mcp.json` |
| Config key | `mcpServers` |
| Format | JSON |
| Transports | stdio, http, sse |

**Note:** Remote servers use simplified config (just `url` and optional `headers`, no `type` field).

### VS Code

| Property | Value |
|----------|-------|
| Global config (macOS) | `~/Library/Application Support/Code/User/mcp.json` |
| Global config (Windows) | `%APPDATA%/Code/User/mcp.json` |
| Global config (Linux) | `~/.config/Code/User/mcp.json` |
| Project config | `.vscode/mcp.json` |
| Config key | `servers` |
| Format | JSON |
| Transports | stdio, http, sse |

### Gemini CLI

| Property | Value |
|----------|-------|
| Global config | `~/.gemini/settings.json` |
| Project config | `.gemini/settings.json` |
| Config key | `mcpServers` |
| Format | JSON |
| Transports | stdio, http, sse |

### Codex

| Property | Value |
|----------|-------|
| Global config | `~/.codex/config.toml` |
| Project config | `.codex/config.toml` (trusted projects only) |
| Config key | `mcp_servers` |
| Format | TOML |
| Transports | stdio, **streamable HTTP** (SSE for local servers is **not supported**; legacy HTTP+SSE remote endpoints are accepted) |

**Advanced TOML fields** (beyond what add-mcp configures):

```toml
[mcp_servers.my-server]
enabled = true                              # Enable/disable (default: true)
required = true                             # Fail startup if can't init
command = "npx"                             # Stdio: command to run
args = ["-y", "@org/mcp-server"]            # Stdio: command arguments
cwd = "/path/to/server"                     # Stdio: working directory
url = "https://example.com/mcp"             # HTTP: server endpoint
bearer_token_env_var = "MY_TOKEN"           # HTTP: auth token env var
startup_timeout_sec = 10.0                  # Startup timeout (default: 10)
tool_timeout_sec = 60.0                     # Per-tool timeout (default: 60)
enabled_tools = ["search", "summarize"]     # Tool allowlist
disabled_tools = ["slow-tool"]              # Tool denylist
supports_parallel_tool_calls = false        # Allow parallel calls (default false; only for stateless tools)
default_tools_approval_mode = "on-request"  # Per-server default approval mode
oauth_scopes = ["read", "write"]            # Scopes to request during MCP OAuth login

[mcp_servers.my-server.approval_mode]       # Per-tool approval overrides
search = "never"
delete = "untrusted"

[mcp_servers.my-server.env]                 # Environment variables
API_KEY = "value"

[mcp_servers.my-server.http_headers]        # Static HTTP headers
X-Custom = "value"

[mcp_servers.my-server.env_http_headers]    # Headers from env vars
Authorization = "AUTH_TOKEN_ENV"
```

**Remote-executor stdio (experimental):**
```toml
[mcp_servers.my-server]
experimental_environment = "remote"
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]
```

**OAuth support:**
```toml
mcp_oauth_callback_port = 8080              # Fixed port for OAuth callback (else ephemeral)
mcp_oauth_callback_url  = "http://localhost:8080/cb"  # Override redirect_uri
mcp_oauth_credentials_store = "auto"        # auto | file | keyring
mcp_oauth_resource = "https://example.com"  # Optional RFC 8707 resource parameter

[features]
experimental_use_rmcp_client = true         # Required for new OAuth flow on first MCP setup
```

**Allowlist (admin / `requirements.toml`):**
```toml
[mcp_servers.docs]
identity = { command = "codex-mcp" }        # Stdio: only allow when command matches
# identity = { url = "https://...mcp" }     # HTTP: only allow when URL matches
```

**Built-in commands:** `codex mcp add`, `codex mcp list [--json]`, `codex mcp get`, `codex mcp remove`, `codex mcp login <server>` (OAuth), `codex mcp logout <server>`. The `/mcp verbose` slash command (added v0.123) provides full server diagnostics inside the TUI.

**Add server example:**
```bash
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add sentry --env SENTRY_AUTH_TOKEN=... -- url=https://mcp.sentry.dev/mcp
```

### Goose

| Property | Value |
|----------|-------|
| Global config (macOS/Linux) | `~/.config/goose/config.yaml` |
| Global config (Windows) | `%APPDATA%/Block/goose/config/config.yaml` |
| Project config | Not supported (global only) |
| Config key | `extensions` |
| Format | YAML |
| Transports | stdio, http, sse |

**Transformation:** Uses `uri` instead of `url`, `streamable_http` instead of `http`, `cmd` instead of `command`, `envs` instead of `env`.

### GitHub Copilot CLI

| Property | Value |
|----------|-------|
| Global config | `~/.copilot/mcp-config.json` |
| Project config | `.vscode/mcp.json` (shared with VS Code) |
| Config key (global) | `mcpServers` |
| Config key (project) | `servers` |
| Format | JSON |
| Transports | stdio, http, sse |

**Transformation:** Global config adds `tools: ["*"]` to each server entry.

### OpenCode

| Property | Value |
|----------|-------|
| Global config | `~/.config/opencode/opencode.json` |
| Project config | `opencode.json` (or `.opencode/opencode.json`) |
| Config key | `mcp` |
| Format | JSON / JSONC |
| Transports | stdio (`type: "local"`), http (`type: "remote"`) |

**Transformation:** Uses explicit `type: "remote"` / `type: "local"`, `command` as a single array (command + args together), `environment` instead of `env`, per-server `enabled` boolean, optional `oauth: true` for OAuth-protected remotes, and `timeout` in milliseconds.

**Local example:**
```json
{
  "mcp": {
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": { "DATABASE_URL": "{env:DATABASE_URL}" },
      "enabled": true,
      "timeout": 5000
    }
  }
}
```

**Remote example (OAuth):**
```json
{
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": true,
      "enabled": true
    }
  }
}
```

**CLI:** `opencode mcp add`, `opencode mcp list`, `opencode mcp auth <name>`, `opencode mcp logout <name>`, `opencode mcp debug <name>`. Variable substitution via `{env:VAR}` and `{file:path}`. See [opencode-mcp.md](opencode-mcp.md) for the full reference, including known plugin-hook caveats for MCP calls.

### Devin CLI / Desktop

| Property | Value |
|----------|-------|
| Global config (macOS/Linux) | `~/.config/devin/mcp_config.json` |
| Global config (Windows) | `%APPDATA%/devin/mcp_config.json` |
| Project config | `.devin/mcp_config.json`, `.devin/mcp_config.local.json` (gitignored) |
| Config key | `mcpServers` |
| Format | JSON |
| Transports | stdio (`command`/`args`/`env`), http (`url` + `transport: "http"`) |

**Note:** Dedicated `mcp_config.json` files since v3000.3 (Local 3.6); older
versions keep servers under `mcpServers` in `config.json` and migrate them on
startup. Devin also imports MCP/rules config from `AGENTS.md`, `.cursor/rules`,
`.windsurf/rules`, and `.claude/` when `read_config_from` is enabled (default).

### Zed

| Property | Value |
|----------|-------|
| Global config (macOS/Windows) | `~/Library/Application Support/Zed/settings.json` |
| Global config (Linux) | `~/.config/zed/settings.json` |
| Project config | `.zed/settings.json` |
| Config key | `context_servers` |
| Format | JSON |
| Transports | stdio, http, sse |

**Transformation:** Adds `source: "custom"` to each entry.

## Config Format Examples

### JSON (most agents)

```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    },
    "stripe": {
      "type": "http",
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer ${STRIPE_API_KEY}"
      }
    }
  }
}
```

### YAML (Goose)

```yaml
extensions:
  neon:
    name: neon
    type: streamable_http
    uri: https://mcp.neon.tech/mcp
    headers: {}
    enabled: true
    timeout: 300
  postgres:
    name: postgres
    cmd: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-postgres"
    type: stdio
    envs: {}
    enabled: true
    timeout: 300
```

### TOML (Codex)

```toml
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]

[mcp_servers.stripe]
type = "http"
url = "https://mcp.stripe.com"

[mcp_servers.stripe.headers]
Authorization = "Bearer ${STRIPE_API_KEY}"
```

## Agent-Specific Transformations

When installing manually (without add-mcp), be aware of these config variations:

| Agent | Config Key | URL Field | Command Field | Env Field | Extra Fields |
|-------|-----------|-----------|--------------|-----------|--------------|
| Claude Code | `mcpServers` | `url` | `command` | `env` | - |
| Claude Desktop | `mcpServers` | `url` | `command` | `env` | - |
| Cursor | `mcpServers` | `url` | `command` | `env` | No `type` for remote |
| VS Code | `servers` | `url` | `command` | `env` | - |
| Gemini CLI | `mcpServers` | `url` | `command` | `env` | - |
| Codex | `mcp_servers` | `url` | `command` | `env` | TOML; HTTP-only remote (no local SSE); `bearer_token_env_var`, `oauth_scopes`, `supports_parallel_tool_calls` |
| Goose | `extensions` | `uri` | `cmd` | `envs` | `name`, `enabled`, `timeout` |
| GitHub Copilot CLI | `mcpServers` | `url` | `command` | `env` | `tools: ["*"]` (global) |
| OpenCode | `mcp` | `url` | `command` (array) | `environment` | `type: "remote"/"local"` |
| Zed | `context_servers` | `url` | `command` | `env` | `source: "custom"` |

## Manual Multi-Agent Setup

If you need to install to agents without using `npx add-mcp`, edit each agent's config file directly. The key differences to handle:

1. **Find the config file** from the agent reference table above
2. **Use the correct config key** (`mcpServers`, `servers`, `extensions`, etc.)
3. **Apply transformations** for agents that use different field names
4. **Use the correct format** (JSON for most, YAML for Goose, TOML for Codex)

For team projects, prefer project-level configs (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`) so all team members get the same MCP servers. Commit these files to version control.

# OpenCode MCP Reference

Detailed MCP server configuration for [anomalyco/opencode](https://github.com/anomalyco/opencode) (v1.14.x).

## Contents

- [Config Locations](#config-locations)
- [Server Types](#server-types)
- [Local (stdio) Server](#local-stdio-server)
- [Remote (http) Server](#remote-http-server)
- [OAuth and Auth](#oauth-and-auth)
- [Tool Permissions for MCP](#tool-permissions-for-mcp)
- [CLI Commands](#cli-commands)
- [Field Differences vs Other Agents](#field-differences-vs-other-agents)

## Config Locations

| Scope | Path |
|-------|------|
| Global | `~/.config/opencode/opencode.json` |
| Project | `<project>/opencode.json` (or `.opencode/opencode.json`) |

The MCP config lives under the top-level `mcp` key. Multiple files merge (later wins; project overrides global).

## Server Types

```json
{
  "mcp": {
    "<server-name>": {
      "type": "local",   // or "remote"
      ...
    }
  }
}
```

OpenCode requires the `type` field — there is no implicit default.

## Local (stdio) Server

```json
{
  "mcp": {
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": {
        "DATABASE_URL": "{env:DATABASE_URL}"
      },
      "enabled": true,
      "timeout": 5000
    }
  }
}
```

| Field | Type | Notes |
|-------|------|-------|
| `type` | string | Must be `"local"` for stdio |
| `command` | string[] | First element is the binary; rest are args. **Note: array, not split into `command`/`args`** |
| `environment` | object | Env vars passed to the child process. **Key name is `environment`, NOT `env`** |
| `enabled` | boolean | Default `true`. Set `false` to disable without deleting |
| `timeout` | number (ms) | Tool-fetching timeout (default `5000`) |

## Remote (http) Server

```json
{
  "mcp": {
    "stripe": {
      "type": "remote",
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer {env:STRIPE_API_KEY}"
      },
      "enabled": true,
      "timeout": 30000
    }
  }
}
```

| Field | Type | Notes |
|-------|------|-------|
| `type` | string | Must be `"remote"` for HTTP/SSE |
| `url` | string | Endpoint |
| `headers` | object | Static HTTP headers; supports `{env:VAR}` substitution |
| `oauth` | boolean / object | OAuth configuration (see below) |
| `enabled` | boolean | Default `true` |
| `timeout` | number (ms) | Per-call timeout |

## OAuth and Auth

For servers that require OAuth (GitHub, Sentry, Linear, etc.):

```json
{
  "mcp": {
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": true
    }
  }
}
```

```bash
# Authenticate or re-authenticate
opencode mcp auth github

# Remove stored credentials
opencode mcp logout github

# Diagnose OAuth failures
opencode mcp debug github
```

Tokens are stored alongside other auth in `~/.local/share/opencode/auth.json`.

## Tool Permissions for MCP

Use the `permission` block to control whether MCP tool calls run silently, prompt, or are blocked. Wildcards match tool names:

```json
{
  "permission": {
    "github_*": "allow",
    "stripe_*": "ask",
    "internal_*": "deny"
  }
}
```

**Caveat (as of v1.14.x):** plugin `tool.execute.before` / `tool.execute.after` hooks **do not** fire on MCP tool calls. Plan around this if you rely on plugin-based interception.

## CLI Commands

```bash
# Add a server interactively
opencode mcp add

# List configured servers + connection status
opencode mcp list           # alias: opencode mcp ls

# Authenticate / sign out
opencode mcp auth <name>
opencode mcp logout <name>

# Debug OAuth issues
opencode mcp debug <name>
```

## Field Differences vs Other Agents

| Concept | Claude Code (`mcpServers`) | Codex (`mcp_servers`) | OpenCode (`mcp`) |
|---------|----------------------------|------------------------|------------------|
| Top-level key | `mcpServers` | `mcp_servers` | `mcp` |
| Format | JSON | TOML | JSON / JSONC |
| Local command | `command` (string) + `args` (array) | `command` (string) + `args` (array) | `command` (single array, command + args together) |
| Env vars | `env` | `env` | `environment` |
| Enable/disable | (omit to remove) | `enabled = true/false` | `enabled: true/false` |
| Remote type | `type: "http"` or `"sse"` | `url` (auto-detected) | `type: "remote"` |
| Local type | `type: "stdio"` | (default for command) | `type: "local"` |
| Bearer token env | `headers.Authorization` | `bearer_token_env_var` | `headers.Authorization` |
| OAuth flag | (handled by `/mcp`) | `mcp_oauth_callback_port` | `oauth: true` per server |

## Variable Substitution

Inside any string value, OpenCode supports:
- `{env:VAR_NAME}` — read env var
- `{file:./path}` — inline file contents

## Full Multi-Server Example

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": {
        "DATABASE_URL": "{env:DATABASE_URL}"
      },
      "enabled": true,
      "timeout": 10000
    },
    "github": {
      "type": "remote",
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": true,
      "enabled": true
    },
    "stripe": {
      "type": "remote",
      "url": "https://mcp.stripe.com",
      "headers": {
        "Authorization": "Bearer {env:STRIPE_API_KEY}"
      },
      "enabled": false
    }
  },
  "permission": {
    "github_*": "allow",
    "stripe_*": "ask"
  }
}
```

## Sources

- https://opencode.ai/docs/mcp-servers/
- https://opencode.ai/docs/cli/
- https://opencode.ai/docs/config/
- https://opencode.ai/docs/permissions/

# MCP Installation Scopes

## Contents

- [Scope Types](#scope-types)
- [Config File Locations](#config-file-locations)
- [Scope Precedence](#scope-precedence)
- [Config File Examples](#config-file-examples)
- [Managed MCP (Enterprise)](#managed-mcp-enterprise)

## Scope Types

### Local Scope (Default)

```bash
claude mcp add --transport http stripe https://mcp.stripe.com
# or explicitly:
claude mcp add --scope local --transport http stripe https://mcp.stripe.com
```

- **Storage**: `~/.claude.json` under project's path key
- **Visibility**: Only you, only current project
- **Use when**: Personal dev servers, sensitive credentials, experimental configs

### Project Scope

```bash
claude mcp add --scope project --transport http paypal https://mcp.paypal.com/mcp
```

- **Storage**: `.mcp.json` at project root
- **Visibility**: Everyone via version control
- **Use when**: Team-shared servers, project-specific integrations

### User Scope

```bash
claude mcp add --scope user --transport http hubspot https://mcp.hubspot.com/anthropic
```

- **Storage**: `~/.claude.json` (global section)
- **Visibility**: Only you, all projects
- **Use when**: Personal utilities, cross-project tools

## Config File Locations

| Scope | File | Section |
|-------|------|---------|
| Local | `~/.claude.json` | `projects.<project-path>.mcpServers` |
| Project | `.mcp.json` (project root) | `mcpServers` |
| User | `~/.claude.json` | `mcpServers` |

## Scope Precedence

When servers with the same name exist at multiple scopes:

1. **Local** (highest priority)
2. **Project**
3. **User** (lowest priority)

This allows overriding team configs with personal preferences.

## Config File Examples

### Local/User scope (~/.claude.json)

```json
{
  "mcpServers": {
    "my-global-server": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    }
  },
  "projects": {
    "/path/to/project": {
      "mcpServers": {
        "project-db": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
          "env": {
            "API_KEY": "${MY_API_KEY}"
          }
        }
      }
    }
  }
}
```

### Project scope (.mcp.json)

```json
{
  "mcpServers": {
    "project-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}
```

### Environment Variables in Config

Syntax: `${VAR}` or `${VAR:-default}`

```json
{
  "mcpServers": {
    "api": {
      "type": "http",
      "url": "${API_URL:-https://default.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
```

## Managed MCP (Enterprise)

System administrators can control MCP via managed configuration files.

### File Locations

| Platform | Location |
|----------|----------|
| macOS | `/Library/Application Support/ClaudeCode/managed-mcp.json` |
| Linux/WSL | `/etc/claude-code/managed-mcp.json` |
| Windows | `C:\Program Files\ClaudeCode\managed-mcp.json` |

### Exclusive Control

Takes complete control; users cannot modify:

```json
{
  "mcpServers": {
    "company-api": {
      "type": "http",
      "url": "https://internal.company.com/mcp"
    }
  }
}
```

### Allowlist/Denylist Control

```json
{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://mcp.company.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}
```

# MCP Server Search & Verification

## Contents

- [Search Workflow](#search-workflow)
- [Deployment Options](#deployment-options)
- [Known Official Vendor Servers](#known-official-vendor-servers)
- [MCP Reference Servers](#mcp-reference-servers)
- [User Choice Template](#user-choice-template)
- [Collecting Configuration](#collecting-configuration)

## Search Workflow

**ALWAYS search for official vendor source FIRST, then fallback to MCP Registry.**

### Step 1: Find Official Vendor Source

Use WebSearch:
```
"[service-name] MCP server official"
"[service-name] Model Context Protocol GitHub"
site:github.com [vendor-name] mcp-server
```

**Verify it's official:**
- GitHub org matches vendor name (e.g., `github/github-mcp-server`)
- Links from vendor's official website
- Mentioned in vendor's official docs

### Step 2: Fetch Installation Details

Use WebFetch on the official repo README to get:
- Available deployment options (Remote, Local, Docker)
- Vendor's recommended approach
- Required environment variables
- Authentication requirements

### Step 3: Fallback to MCP Registry

Only if no official source found:
```
https://registry.modelcontextprotocol.io/v0.1/servers?search=<query>&limit=20
```

**Response fields:**
- `server.name` - Server identifier
- `server.description` - What it does
- `server.repository.url` - Source code
- `server.remotes[].url` - Remote endpoint
- `server.packages[].identifier` - npm package name
- `server.packages[].environmentVariables` - Required config

## Deployment Options

### Remote (HTTP/SSE)
```bash
claude mcp add --transport http <name> <url>
```
**Pros:** No local setup, always updated, vendor-managed
**Cons:** Requires internet
**Best for:** Most users, production

### Local (npm/Stdio)
```bash
claude mcp add --transport stdio <name> -- npx -y @vendor/mcp-server
```
**Pros:** Works offline, full control
**Cons:** Requires Node.js, manual updates
**Best for:** Offline use, development

### Docker
```bash
claude mcp add --transport stdio <name> -- docker run -i --rm vendor/mcp-server
```
**Pros:** Isolated, reproducible
**Cons:** Requires Docker
**Best for:** CI/CD, isolation requirements

## Known Official Vendor Servers

### Developer Tools & Platforms

| Service | Official Repo | Remote URL | Local Package |
|---------|---------------|------------|---------------|
| GitHub | `github/github-mcp-server` | `https://api.githubcopilot.com/mcp/` | `@github/mcp-server` |
| GitLab | `gitlab.com` (docs) | `https://gitlab.com/-/mcp` | - |
| Atlassian | `atlassian/atlassian-mcp-server` | `https://mcp.atlassian.com/v1/mcp` | - |
| Linear | `linear.app` (docs) | `https://mcp.linear.app/sse` | - |
| JetBrains | JetBrains official | Via IDE integration | - |
| Vercel | `vercel` (in MCP registry) | - | `@vercel/mcp` |
| Heroku | `heroku/heroku-mcp-server` | - | `@heroku/mcp` |

### Cloud & Infrastructure

| Service | Official Repo | Remote URL | Local Package |
|---------|---------------|------------|---------------|
| Cloudflare | `cloudflare/mcp-server-cloudflare` | Multiple remote servers | `@cloudflare/mcp-server` |
| AWS | `awslabs/mcp` | - | AWS MCP servers |
| Google Cloud Run | `GoogleCloudPlatform/cloud-run-mcp` | - | - |
| Microsoft Azure | `microsoft/mcp` | - | Azure MCP Server |

### Databases

| Service | Official Repo | Remote URL | Local Package |
|---------|---------------|------------|---------------|
| MongoDB | `mongodb-js/mongodb-mcp-server` | - | `@mongodb-js/mongodb-mcp-server` |
| Redis | `redis/mcp-redis` | - | `@redis/mcp` |
| Supabase | `supabase-community/supabase-mcp` | - | `@supabase/mcp` |
| Neon | `neondatabase/mcp-server-neon` | - | `@neondatabase/mcp-server-neon` |

### Productivity & Communication

| Service | Official Repo | Remote URL | Local Package |
|---------|---------------|------------|---------------|
| Notion | `makenotion/notion-mcp-server` | `https://mcp.notion.com/mcp` | - |
| Slack | `zencoderai/slack-mcp-server` | - | `@modelcontextprotocol/server-slack` |
| HubSpot | `developer.hubspot.com` | `https://mcp.hubspot.com/anthropic` | - |
| Monday.com | `mondaycom/mcp` | - | `@mondaycom/mcp` |
| Asana | Asana official | `https://mcp.asana.com/sse` | - |

### Observability & Monitoring

| Service | Official Repo | Remote URL | Local Package |
|---------|---------------|------------|---------------|
| Sentry | Sentry official | `https://mcp.sentry.dev/mcp` | - |
| Datadog | `Datadog-Official/Datadog-MCP` | - | Datadog MCP |
| Grafana | `grafana/mcp-grafana` | - | `@grafana/mcp-grafana` |

### Code Intelligence

| Service | Official Repo | Remote URL | Local Package |
|---------|---------------|------------|---------------|
| CodeAlive | `CodeAlive-AI/codealive-mcp` | `https://mcp.codealive.ai/api` | `codealive-mcp` (Python) |

### Other Services

| Service | Official Repo | Remote URL | Local Package |
|---------|---------------|------------|---------------|
| Twilio | `twilio-labs/mcp` | - | Twilio MCP |
| Firebase | `firebase/firebase-tools` | - | Firebase MCP |
| Auth0 | `auth0/auth0-mcp-server` | - | `@auth0/mcp` |

## MCP Reference Servers

From Anthropic/MCP team:

| Server | Package | Description |
|--------|---------|-------------|
| Filesystem | `@modelcontextprotocol/server-filesystem` | File operations |
| Git | `@modelcontextprotocol/server-git` | Git repository access |
| Memory | `@modelcontextprotocol/server-memory` | Knowledge graph storage |
| SQLite | `@modelcontextprotocol/server-sqlite` | SQLite database access |
| Fetch | `@modelcontextprotocol/server-fetch` | Web content fetching |
| Time | `@modelcontextprotocol/server-time` | Time and timezone conversion |
| Sequential Thinking | `@modelcontextprotocol/server-sequentialthinking` | Problem-solving workflows |

## User Choice Template

When presenting options, use `AskUserQuestion` with this format:

```
Found [Service] MCP Server (Official ✓)

Available deployment options:

1. **Remote (Recommended)** ⭐
   No setup required, always up-to-date
   → claude mcp add --transport http [name] [url]

2. **Local (npm)**
   Works offline, requires Node.js
   → claude mcp add --transport stdio [name] -- npx -y @package

3. **Docker**
   Isolated environment, requires Docker
   → claude mcp add --transport stdio [name] -- docker run -i image

Which would you like to install?
```

Mark vendor's recommended option (or Remote if not specified) with ⭐.

## Collecting Configuration

**IMPORTANT:** Check if server requires configuration before installing. Use `AskUserQuestion`:

```
This MCP server requires configuration:

**Required:**
- API_KEY: Your [Service] API key (get it from [url])
- WORKSPACE_ID: Your workspace identifier

**Optional:**
- CUSTOM_URL: Custom API endpoint (default: https://api.service.com)

Please provide the required values.
```

Common patterns:
- **API Keys**: Most services require authentication
- **OAuth**: GitHub, Atlassian - will prompt in browser
- **Database URLs**: Connection strings like `postgresql://user:pass@host:5432/db`
- **Workspace IDs**: Slack, Notion, Atlassian often need workspace identifiers

Never install with placeholder values.

# MCP Transport Types

## Contents

- [HTTP Transport (Recommended)](#http-transport-recommended)
- [SSE Transport (Deprecated)](#sse-transport-deprecated)
- [Stdio Transport](#stdio-transport)
- [Popular Servers](#popular-servers)

## HTTP Transport (Recommended) — Streamable HTTP

Remote servers accessible via HTTP/HTTPS URLs. As of 2026-04 this is **the only supported remote transport** (SSE has reached end-of-life — see below).

```bash
claude mcp add --transport http <name> <url>

# With custom headers
claude mcp add --transport http <name> <url> --header "Authorization: Bearer TOKEN"

# Add via JSON
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_PAT"}}'
```

**Config format:**
```json
{
  "mcpServers": {
    "server-name": {
      "type": "http",
      "url": "https://api.example.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

**Best for:** Cloud services, SaaS integrations, OAuth-protected APIs.

**OAuth (2026):** HTTP transport supports OAuth 2.1 with RFC 9728 Protected Resource Metadata discovery, Client ID Metadata Document (CIMD / SEP-991), `oauth.authServerMetadataUrl` override, and step-up authorization via `insufficient_scope` 403 responses.

**Large tool results:** annotate MCP responses with `_meta["anthropic/maxResultSizeChars"]` (up to 500K) to avoid truncation of bulky payloads (e.g. DB schemas).

**Helper script env vars** (for `headersHelper`-style auth scripts): `CLAUDE_CODE_MCP_SERVER_NAME`, `CLAUDE_CODE_MCP_SERVER_URL`.

## SSE Transport (Deprecated)

Server-Sent Events transport. **Deprecated by the MCP spec (2025-03-26 revision). Connections stop being accepted on April 1, 2026** — already past as of today (2026-04-26). Migrate any `"transport": "sse"` configs to `--transport http` (Streamable HTTP). Most servers that supported SSE accept Streamable HTTP on the same URL.

```bash
claude mcp add --transport sse <name> <url>   # legacy only
```

**Config format:**
```json
{
  "mcpServers": {
    "server-name": {
      "type": "sse",
      "url": "https://example.com/sse"
    }
  }
}
```

## Stdio Transport

Local servers via subprocess execution. Required for npm packages.

```bash
claude mcp add --transport stdio <name> -- <command> [args...]
```

**Config format:**
```json
{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "/path/to/server",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "DEBUG": "true"
      }
    }
  }
}
```

**Best for:** Local databases, npm packages, custom scripts.

## Popular Servers

### Stdio Servers

| Server | Command |
|--------|---------|
| Filesystem | `npx -y @modelcontextprotocol/server-filesystem /path` |
| PostgreSQL | `npx -y @bytebase/dbhub --dsn "postgresql://..."` |
| SQLite | `npx -y @modelcontextprotocol/server-sqlite path/to/db.sqlite` |
| Brave Search | `npx -y @anthropics/mcp-server-brave-search` |
| Puppeteer | `npx -y @anthropics/mcp-server-puppeteer` |

### HTTP Servers

| Service | URL |
|---------|-----|
| GitHub | `https://api.githubcopilot.com/mcp/` |
| Sentry | `https://mcp.sentry.dev/mcp` |
| Notion | `https://mcp.notion.com/mcp` |
| Asana | `https://mcp.asana.com/sse` (SSE) |
| Linear | `https://mcp.linear.app/sse` (SSE) |

Browse more: https://github.com/modelcontextprotocol/servers

# MCP Troubleshooting

## Contents

- [Check Server Status](#check-server-status)
- [Common Issues](#common-issues)
- [Environment Variables](#environment-variables)
- [Security Notes](#security-notes)
- [Resources](#resources)

## Check Server Status

```bash
# In Claude Code
/mcp

# CLI commands
claude mcp list
claude mcp get <server-name>
```

## Common Issues

### "Options must come before server name"

**Wrong:**
```bash
claude mcp add my-server --transport http https://example.com
```

**Correct:**
```bash
claude mcp add --transport http my-server https://example.com
```

### Server Not Connecting

1. **Check URL** - Must be full URL with protocol
2. **Verify credentials** - Run `/mcp` to re-authenticate
3. **Check timeout** - Increase with `MCP_TIMEOUT=30000 claude`

### Stdio Server Fails to Start

1. **Verify command exists:**
   ```bash
   which npx
   npx -y @package/name --help
   ```

2. **Check environment variables:**
   ```bash
   echo $API_KEY
   ```

3. **Windows** - Use `cmd /c` wrapper:
   ```bash
   claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
   ```

### Output Truncated

MCP output is limited to 25,000 tokens by default. Increase with:

```bash
export MAX_MCP_OUTPUT_TOKENS=50000
claude
```

### OAuth Authentication Issues

1. Run `/mcp` in Claude Code
2. Follow browser prompts
3. Tokens refresh automatically

If issues persist, remove and re-add the server:
```bash
claude mcp remove github
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
```

### Environment Variable Not Expanding

**Syntax:**
- `${VAR}` - Expands to value
- `${VAR:-default}` - Uses default if not set

**Verify variable:**
```bash
echo $MY_API_KEY
```

**In config:**
```json
{
  "env": {
    "API_KEY": "${MY_API_KEY}"
  }
}
```

### --env Flag Issues

The `--env` CLI flag can misinterpret arguments with special characters. Workaround: add server without env vars, then edit config file directly. See [scopes.md](scopes.md) for file locations.

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `MCP_TIMEOUT` | Server startup timeout (ms) | 10000 |
| `MAX_MCP_OUTPUT_TOKENS` | Maximum output tokens | 25000 |
| `CLAUDE_CODE_MCP_SERVER_NAME` | Set inside `headersHelper` scripts | (auto) |
| `CLAUDE_CODE_MCP_SERVER_URL` | Set inside `headersHelper` scripts | (auto) |

## Per-Response Output Limit Override

For very large MCP results (DB schemas, large file listings) that would otherwise be truncated by `MAX_MCP_OUTPUT_TOKENS`, the server can annotate its response with `_meta["anthropic/maxResultSizeChars"]` (max 500_000 chars). Claude Code will pass through results up to that size.

## Security Notes

- Third-party MCP servers are not verified by Anthropic
- Be cautious with servers that fetch untrusted content (prompt injection risk)
- Use local scope for sensitive credentials
- Review project-scoped servers before enabling

## Resources

- MCP Server Directory: https://github.com/modelcontextprotocol/servers
- Build Custom Servers: https://modelcontextprotocol.io/quickstart/server