MCP网关

Requires API Key

See .env.example for all supported environment variables.

Installation

```bash

Or run directly without installing

uvx pmcp

Configure with `pmcp setup`

PMCP includes a wizard-style helper that can render ready-to-use MCP client config for Claude and OpenCode. The generated config only connects your client to the PMCP gateway. Downstream MCP servers stay lazy until first use unless you add them to autoStart in your .mcp.json.

Use pmcp setup to print the generated config:

pmcp setup --client claude --mode stdio    # Claude local stdio
pmcp setup --client claude --mode http     # Claude shared-service HTTP
pmcp setup --client opencode --mode stdio  # OpenCode local stdio
pmcp setup --client opencode --mode http   # OpenCode shared-service HTTP

Named profiles cover the common modes:

pmcp setup --profile local-stdio
pmcp setup --profile shared-local-http
pmcp setup --profile authenticated-shared-http
pmcp setup --profile ci

Write directly into your client config with --write:

pmcp setup --client claude --mode http --write

Without --write, pmcp setup prints the config so you can paste it into: - Claude: ~/.mcp.json - OpenCode: ~/.config/opencode/opencode.json

Use shared-service HTTP mode when running one PMCP service for multiple sessions or clients. Use single-process stdio mode for local testing.

Render client setup snippets

pmcp setup pmcp setup --client claude --mode stdio pmcp setup --client opencode --mode http --write

Docker

```bash

Using Docker

docker run -it --rm \ -v ~/.mcp.json:/home/appuser/.mcp.json:ro \ -v ~/.env:/app/.env:ro \ ghcr.io/viperjuice/pmcp:latest

Using Docker Compose

docker-compose up -d ```

Install with uv (recommended)

uv sync --all-extras

Quick Start

Example: Adding GitHub Support

You: "I need to manage GitHub issues"

gateway.request_capability({ query: "github issues" })

Returns (if not already configured):

{
  "status": "candidates",
  "candidates": [{
    "name": "github",
    "candidate_type": "server",
    "is_running": false,
    "requires_api_key": true,
    "env_var": "GITHUB_PERSONAL_ACCESS_TOKEN",
    "env_instructions": "Create at https://github.com/settings/tokens with repo scope"
  }]
}

Start with bearer auth from the environment

PMCP_AUTH_TOKEN=mysecrettoken pmcp --transport http

Avoid passing production tokens with `--auth-token`; command-line arguments can
be visible in process listings on shared hosts.

Clients must then include `Authorization: Bearer mysecrettoken` on `/mcp` requests.
`/health` and `/metrics` remain unauthenticated by design; protect them with
firewall rules, IP allowlists, or reverse-proxy policy before any non-localhost
exposure.

**Assumptions and trust model:**

- PMCP binds to `127.0.0.1` by default — not safe to expose publicly without
  `PMCP_AUTH_TOKEN`.
- Config files (`.mcp.json`) are trusted inputs — treat them like code; do not load untrusted configs.
- Secrets in `.env` files are passed to child MCP server processes; protect the `.env` file with filesystem permissions.

**Production background service (Linux systemd):**

~/.config/systemd/user/pmcp.service

[Unit] Description=PMCP MCP Gateway

[Service] Environment=PMCP_AUTH_TOKEN=replace-with-secret-token ExecStart=/usr/local/bin/pmcp --transport http Restart=on-failure

[Install] WantedBy=default.target

Or with nohup:

Optional Eager Startup

Packaged manifest servers do not start automatically. They are lazy by default: PMCP can discover or provision them from the manifest, then connect on first use.

To eagerly start a server every time PMCP starts, list it in top-level autoStart:

{
  "autoStart": ["playwright", "context7"],
  "mcpServers": {}
}

Common opt-in choices:

Startup policy decisions are visible through gateway.health and live pmcp status --verbose. Health rows keep the existing name, status, tool_count, and error fields, and may also include:

For persistent administration, use the config tools:

gateway.config_status({})
gateway.get_startup_policy({})
gateway.set_startup_policy({
  "operation": "add",
  "names": ["playwright"],
  "source": "project"
})

gateway.set_startup_policy is preview-only by default. To write, select exactly one source or path and pass both "apply": true and "dry_run": false. The writer updates only top-level autoStart, preserves unrelated .mcp.json keys and server definitions, writes atomically, and returns a refresh next step instead of silently reconnecting servers. Diagnostics report stale autoStart, legacy disableAutoStart conflicts, policy-denied rows, and missing-auth rows without printing secret values.

PMCP negotiates the current MCP protocol version with downstream servers and continues to connect to older supported servers. The local conformance matrix covers negotiated status handling for 2024-11-05, 2025-03-26, 2025-06-18, and 2025-11-25, with 2025-11-25 preferred for new initialization attempts. gateway.health and pmcp status --json can include the negotiated protocol_version and declared server capabilities when a connected server reports them.

Modern MCP task support is conservative. PMCP forwards task-augmented tool calls only when a tool advertises execution.taskSupport and the downstream server advertises task capability. Required-task tools fail before dispatch if the server does not advertise task support. Task records are transient gateway state, not durable PMCP storage.

The tenant code-mode host contract in specs/tenant-code-mode-host-contract.md freezes the PMCP/companion-server boundary for future hosted sandbox execution. PMCP remains the broker; the companion tenant server remains the execution authority.

Gateway observability is local and structured. gateway.invoke accepts trace context through _meta.traceparent, _meta.tracestate, and _meta.baggage and preserves those string values on PMCP-owned downstream request metadata. The same keys are tolerated on HTTP requests. PMCP does not require or configure an OpenTelemetry exporter.

gateway.health may include gateway_diagnostics and recent audit_events. Diagnostics report transport/header compatibility, trace support, audit buffer readiness, auth metadata presence, and rate-limit configuration without secret values. Audit events are bounded in memory and include method/action, server or tool identity, protocol version when known, task ID when present, outcome, latency, auth state, and redacted error text.

PMCP's Streamable HTTP endpoint remains compatible with existing clients that send no draft headers. It also tolerates MCP-Protocol-Version, Mcp-Method, and Mcp-Name request headers for clients experimenting with draft MCP transport conventions. These headers are compatibility inputs, not a promise that PMCP implements every draft MCP extension.

Servers stopped with gateway.disconnect_server remain visible in health as offline or lazy when PMCP still knows their configuration, and startup policy observation fields are preserved.

Example missing-auth health row:

{
  "name": "github",
  "status": "offline",
  "tool_count": 0,
  "startup_policy": "skipped",
  "startup_source": "manifest",
  "startup_skip_reason": "missing_auth",
  "startup_env_var": "GITHUB_PERSONAL_ACCESS_TOKEN"
}

Guidance Configuration

Create ~/.claude/gateway-guidance.yaml:

guidance:
  level: "minimal"  # Options: "off", "minimal", "standard"

  layers:
    mcp_instructions: true   # L0 philosophy
    code_hints: true         # L1 hints
    code_snippets: false     # L2 examples (default: off)
    methodology_resource: true  # L3 guide

Levels: - minimal (default): L0 + L1 (~200 tokens overhead) - standard: L0 + L1 + L2 (~320 tokens overhead) - off: No guidance

Configuration

Config Discovery

PMCP discovers MCP servers from:

1. Project config: .mcp.json in project root (highest priority)
2. User config: ~/.mcp.json or ~/.claude/.mcp.json
3. Custom config: Via --config flag or PMCP_CONFIG env var

Initialize config (interactive)

pmcp init

Environment variable

export PMCP_LOCK_DIR=/custom/path pmcp

**Per-project lock (not recommended):**

1. Set API key (if required)

export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...

No API Key Required

CLI Commands

```bash

CLI flag

pmcp --lock-dir /custom/path

Missing API Key

```bash

Progressive Disclosure Workflow

PMCP follows a progressive disclosure pattern - start with natural language, get recommendations, drill down as needed.

Troubleshooting