mcpstead

MCP-шлюз

Единая нисходящая конечная точка /mcp, которая обслуживает множество вышестоящих MCP-серверов. Постоянные вышестоящие соединения с возможностью переподключения, реестр инструментов с квалифицированными именами, ответы в формате JSON или SSE в зависимости от заголовка Accept клиента, аутентификация для каждого вышестоящего сервера, метрики Prometheus.

Установка

# npm (macOS, Linux, WSL)
npm i -g @ahkohd/mcpstead

# homebrew (macOS, Linux)
brew install ahkohd/tap/mcpstead

# cargo
cargo install mcpstead --locked --force

# verify
mcpstead --version

Related MCP server: Mavryn

Быстрый старт

# 1. write a config
mkdir -p ~/.config/mcpstead
cat > ~/.config/mcpstead/config.yaml <<'EOF'
host: 0.0.0.0
port: 8766

mcp:
  auth:
    mode: none

servers:
  - name: example
    url: http://127.0.0.1:3000/mcp
    protocol: streamable
    auth: none
EOF

# 2. run
mcpstead --config ~/.config/mcpstead/config.yaml

Затем укажите любому MCP-клиенту адрес http://127.0.0.1:8766/mcp.

Docker

docker build -t mcpstead .
docker run --rm \
  -p 8766:8766 \
  -v "$PWD/config:/etc/mcpstead:ro" \
  mcpstead

Dockerfile выполняет установку из crates.io.

HTTP API

Настройка MCP-клиента

Локально, без аутентификации:

mcpstead:
  url: http://127.0.0.1:8766/mcp
  tools:
    resources: false
    prompts: false

Bearer-аутентификация:

mcpstead:
  url: http://127.0.0.1:8766/mcp
  headers:
    Authorization: Bearer ${MCPSTEAD_BEARER_TOKEN}
  tools:
    resources: false
    prompts: false

Инструменты отображаются с квалифицированными именами — <server>__<tool> — поэтому несколько вышестоящих серверов могут предоставлять инструменты с одинаковыми именами без конфликтов.

Аутентификация

Нисходящая (клиенты к mcpstead)

По умолчанию аутентификация отсутствует:

mcp:
  auth:
    mode: none

Bearer-аутентификация:

mcp:
  auth:
    mode: bearer

Токен берется из переменной окружения:

export MCPSTEAD_BEARER_TOKEN='replace-with-strong-secret'
mcpstead --config ~/.config/mcpstead/config.yaml

Клиенты отправляют Authorization: Bearer <token>. При отсутствии или неверном токене возвращается 401. Параметр mcp.auth.bearer_token в конфигурации отклоняется при запуске.

/health и /metrics остаются открытыми независимо от режима аутентификации — для мониторинга без раскрытия токена.

Вышестоящая (mcpstead к MCP-серверам)

Настраивается для каждого сервера в списке servers. Три режима:

servers:
  - name: local
    url: http://127.0.0.1:3000/mcp
    auth: none

  - name: workflow
    url: https://workflow.example/mcp-server/http
    auth:
      type: bearer
      token_env: WORKFLOW_TOKEN

  - name: custom
    url: https://api.example/mcp
    headers:
      X-API-Key: '${EXAMPLE_KEY}'

token_env разрешает указанную переменную окружения при запуске и при перезагрузке конфигурации.

Конфигурация

Укажите путь к конфигурации с помощью --config <path> или переменной окружения MCPSTEAD_CONFIG.

host: 0.0.0.0
port: 8766

mcp:
  auth:
    mode: none           # none | bearer
  session:
    idle_ttl_seconds: 3600
    gc_interval_seconds: 60
    shutdown_grace_seconds: 5

servers:
  - name: local
    url: http://127.0.0.1:3000/mcp
    protocol: streamable # streamable | sse | auto
    required: false      # if true, gateway won't start without this upstream
    auth: none
    reconnect:
      max_attempts: 0    # 0 = infinite
      backoff_base_ms: 1000
      backoff_max_ms: 30000
    tools:
      ttl_seconds: 300
    tls_skip_verify: false
    quirks:
      normalize_sse_events: true
      inject_accept_header: 'application/json, text/event-stream'

metrics:
  enabled: true

logging:
  level: info

Горячая перезагрузка

mcpstead перезагружает конфигурацию без перезапуска при:

• SIGHUP (systemctl reload mcpstead или kill -HUP <pid>)

• POST /-/reload (ограничено bearer-аутентификацией в соответствующем режиме)

Можно перезагружать «на лету»:

• список вышестоящих серверов

• аутентификацию, заголовки, особенности (quirks), переподключение, инструменты, URL, протокол и настройки TLS для каждого вышестоящего сервера

• mcp.auth.mode и MCPSTEAD_BEARER_TOKEN

• metrics.enabled

Требуется перезапуск для:

• host

• port

• logging.level

• mcp.session.*

Перезагрузка выполняется по принципу «лучших усилий». Некорректная конфигурация отклоняется и игнорируется; текущая конфигурация остается в силе. Проверяйте логи и mcpstead_config_reloads_total{result="error"} на наличие ошибок.

Ключи конфигурации сессии MCP

• mcp.session.idle_ttl_seconds — удалять неактивные сессии через указанное количество секунд (по умолчанию 3600)

• mcp.session.gc_interval_seconds — интервал запуска сборщика мусора для неактивных сессий (по умолчанию 60)

• mcp.session.shutdown_grace_seconds — максимальное время завершения работы для учета сессий (по умолчанию 5)

Ключи конфигурации для каждого вышестоящего сервера

• name — обязательно, используется как префикс инструмента

• url — обязательно, конечная точка MCP

• protocol — streamable | sse | auto (по умолчанию auto)

• required — блокировать запуск, если вышестоящий сервер не инициализировался (по умолчанию false)

• auth — none, bearer (с token_env) или карта headers

• reconnect.max_attempts — 0 = бесконечно (по умолчанию)

• reconnect.backoff_base_ms / backoff_max_ms — границы экспоненциальной задержки

• tools.ttl_seconds — обновлять кэшированный tools/list через этот интервал

• tls_skip_verify — отключить проверку TLS-сертификатов для этого сервера (по умолчанию false, использовать только в доверенных локальных сетях)

• quirks.normalize_sse_events — удалять строки event: из ответов SSE вышестоящего сервера

• quirks.inject_accept_header — переопределить заголовок Accept, отправляемый вышестоящему серверу

Наблюдаемость

Метрики

/metrics предоставляет счетчики, датчики и гистограммы в формате Prometheus. Кардинальность меток предполагает небольшой ограниченный набор вышестоящих серверов и инструментов; серии вызовов инструментов индексируются по (server, tool).

mcpstead_build_info{version="...",rust_version="...",git_sha="..."}
mcpstead_start_time_seconds
mcpstead_uptime_seconds
mcpstead_process_resident_memory_bytes
mcpstead_process_virtual_memory_bytes
mcpstead_process_cpu_seconds_total
mcpstead_process_open_fds
mcpstead_process_max_fds
mcpstead_process_threads
mcpstead_upstream_connected{server="..."}
mcpstead_upstream_tools_count{server="..."}
mcpstead_upstream_reconnects_total{server="..."}
mcpstead_upstream_last_seen_seconds{server="..."}
mcpstead_upstream_initialize_total{server="...",result="success|error"}
mcpstead_upstream_initialize_duration_seconds_bucket{server="...",le="..."}
mcpstead_upstream_health_checks_total{server="...",result="success|failure"}
mcpstead_upstream_reconnect_attempts_total{server="...",result="success|error"}
mcpstead_upstream_backoff_seconds_total{server="..."}
mcpstead_upstream_in_backoff{server="..."}
mcpstead_upstream_current_backoff_seconds{server="..."}
mcpstead_upstream_session_resets_total{server="...",reason="unknown_session|expired|terminated"}
mcpstead_upstream_tools_refresh_total{server="...",result="success|error"}
mcpstead_upstream_tools_refresh_duration_seconds_bucket{server="...",le="..."}
mcpstead_upstream_tools_last_refresh_timestamp_seconds{server="..."}
mcpstead_upstream_bytes_total{server="...",direction="sent|received"}
mcpstead_downstream_sessions_active
mcpstead_downstream_sessions_total
mcpstead_downstream_session_duration_seconds_bucket{le="..."}
mcpstead_downstream_session_terminations_total{reason="..."}
mcpstead_mcp_requests_total{method="...",result="success|error"}
mcpstead_mcp_request_duration_seconds_bucket{method="...",le="..."}
mcpstead_mcp_auth_attempts_total{result="success|failure"}
mcpstead_mcp_auth_failures_total{reason="..."}
mcpstead_config_reloads_total{result="success|error"}
mcpstead_config_last_reload_timestamp_seconds
mcpstead_tool_calls_total{server="...",tool="..."}
mcpstead_tool_call_errors_total{server="...",tool="...",reason="..."}
mcpstead_tool_call_duration_seconds_bucket{server="...",tool="...",le="..."}

Конфигурация сбора метрик

- job_name: mcpstead
  metrics_path: /metrics
  static_configs:
    - targets: ['mcpstead:8766']

Проверка работоспособности (Health check)

curl http://127.0.0.1:8766/health

Возвращает JSON: состояние соединения с каждым вышестоящим сервером, количество инструментов, время последнего успешного контакта, количество переподключений, последняя ошибка.

Устранение неполадок

• Список всех инструментов пуст — как минимум один вышестоящий сервер не смог выполнить initialize. Проверьте /health для получения статуса по каждому серверу; проверьте URL вышестоящего сервера, аутентификацию и доступность.

• Случайные ошибки SSE parse failed — вышестоящий сервер отправляет диалект SSE, который mcpstead не распознает. Попробуйте установить quirks.normalize_sse_events: true для этого сервера или установите quirks.inject_accept_header: 'application/json', чтобы принудительно использовать JSON.

• tools/call возвращает ошибку аутентификации — вышестоящий сервер отклонил bearer-токен. Убедитесь, что token_env разрешается в правильное значение при запуске; проверьте ожидаемое имя заголовка вышестоящего сервера.

• Ошибки рукопожатия TLS при работе с вышестоящим сервером с самоподписанным сертификатом — установите tls_skip_verify: true для этого сервера. Безопасно только в доверенных локальных сетях.

• 401 от /mcp в режиме bearer — клиент не отправил или отправил неверный Authorization: Bearer <token>. Убедитесь, что MCPSTEAD_BEARER_TOKEN совпадает с тем, что отправляет клиент.

• Вышестоящий сервер постоянно переходит в красный статус в /health — проверьте mcpstead_upstream_reconnects_total и mcpstead_upstream_last_seen_seconds. Настройте reconnect.backoff_max_ms, если вышестоящему серверу требуется больше времени для восстановления.