de en es ja ko ru zh

mcpstead

Name: mcpstead
Author: ahkohd

by ahkohd

Overview Schema Source Related Servers Discussions Admin

Rust

Remote

mcpstead

npm version Crates.io License

MCPゲートウェイ

多数のアップストリームMCPサーバーをフロントエンドとして統合する、単一のダウンストリーム /mcp エンドポイントを提供します。再接続機能付きの永続的なアップストリーム接続、修飾名によるツールレジストリ、クライアントの Accept ヘッダーに基づくJSONまたはSSEレスポンス、アップストリームごとの認証、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

メソッド	パス	用途
`POST`	`/mcp`	HTTP JSON-RPC経由のMCP
`GET`	`/mcp`	405を返します
`DELETE`	`/mcp`	ダウンストリームセッションを終了します
`GET`	`/health`	アップストリームの状態、ツール数、最終確認時刻、再接続回数
`GET`	`/metrics`	Prometheusテキスト形式
`POST`	`/-/reload`	再起動せずに設定をリロードします

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 リスト内でサーバーごとに設定します。3つのモードがあります:

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モードでは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 - アイドルセッションGCの実行間隔（デフォルト 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 - アップストリームのSSEレスポンスから event: 行を除去します
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']

ヘルスチェック

curl http://127.0.0.1:8766/health

JSONを返します: アップストリームごとの接続状態、ツール数、最終成功時刻、再接続回数、最後のエラー。

トラブルシューティング

すべてのツールリストが空 - 少なくとも1つのアップストリームが initialize に失敗しています。/health でサーバーごとの状態を確認し、アップストリームのURL、認証、到達可能性を確認してください。
散発的な SSE parse failed - アップストリームがmcpsteadで認識できないSSE方言を送信しています。そのサーバーに対して quirks.normalize_sse_events: true を試すか、quirks.inject_accept_header: 'application/json' を設定してJSONを強制してください。
tools/call が認証エラーを返す - アップストリームがBearerトークンを拒否しました。token_env が起動時に正しい値に解決されているか確認し、アップストリームが期待するヘッダー名を確認してください。
自己署名アップストリームに対するTLSハンドシェイクエラー - そのサーバーで tls_skip_verify: true を設定してください。信頼できるローカルネットワークでのみ安全です。
Bearerモードで /mcp から401が返される - クライアントが Authorization: Bearer <token> を送信していないか、誤っています。MCPSTEAD_BEARER_TOKEN がクライアントの送信内容と一致しているか確認してください。
/health でアップストリームが繰り返し赤色になる - mcpstead_upstream_reconnects_total と mcpstead_upstream_last_seen_seconds を確認してください。アップストリームの復旧に時間がかかる場合は reconnect.backoff_max_ms を調整してください。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

OneDroid SynapseOAuth
ai.onedroid
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Security Observability
1
clawmerchants-mcp-gateway A
io.github.danielxri
MCP Gateway: wrap any MCP server with cold-start retries, uptime SLA, and per-execution MPP billing.
Agent Orchestration Cloud Platforms Developer Tools
22
MANDATE Credential Broker B
io.github.projetnanocorp
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Security
111
ClearPolicyOAuth
app.clearpolicy
Authenticated MCP server for ClearPolicy policy and compliance workflows.
Legal & Compliance Security
2

Related MCP Servers

super-mcp
Developer Tools Agent Orchestration
nidamen
A
license
Not graded
quality
C
maintenance
A gateway that aggregates multiple MCP servers into a single endpoint, namespacing their tools and forwarding calls, so an agent connects to one MCP to access the entire stack.
Updated 3 months ago (2026-06-15 03:18 UTC)
MIT
Mavryn
Agent Orchestration Security Developer Tools
Dnakitare
A
license
Not graded
quality
C
maintenance
Centralized MCP control plane that proxies multiple upstream MCP servers with tool namespacing, filtering, policy enforcement, audit logging, and health checks.
Updated 3 months ago (2026-06-26 18:16 UTC)
5 npm
MIT
MCP Tool AI
Agent Orchestration Developer Tools AI & Machine Learning
dkokane0
F
license
Not graded
quality
B
maintenance
A configurable MCP gateway that runs multiple Streamable HTTP MCP servers and exposes all their tools through a single endpoint, enabling tool aggregation and routing for MCP clients.
Updated 2 months ago (2026-07-20 11:27 UTC)
1
-
mcp-gateway
Developer Tools Agent Orchestration
klutometis
F
license
Not graded
quality
B
maintenance
A generic MCP gateway that aggregates multiple upstream MCP servers into a single FastMCP endpoint, configured via servers.json with support for tool subsetting, renaming, multi-instance routing, and pluggable authentication.
Updated 14 days ago (2026-09-07 10:51 UTC)
-

mcpstead

インストール

クイックスタート

Docker

HTTP API

MCPクライアントの設定

認証

ダウンストリーム (クライアントからmcpsteadへ)

アップストリーム (mcpsteadからMCPサーバーへ)

設定

ホットリロード

MCPセッション設定キー

アップストリームごとの設定キー

可観測性

メトリクス

スクレイプ設定

ヘルスチェック

トラブルシューティング

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

super-mcp

Mavryn

MCP Tool AI

mcp-gateway