HTTP トランスポート¶
MCP サーバーを HTTP 経由で公開します。リモートデプロイ、マルチクライアントの シナリオ、サーバーを長時間稼働のサービスとして動かす本番環境向けに設計されています。
実行¶
MCP_TRANSPORT=http uv run python -m novelai_image_mcp serve
# or via the CLI flag:
uv run python -m novelai_image_mcp serve --transport http
サーバーはデフォルトで 127.0.0.1:8000/mcp にバインドします。MCP_HOST /
MCP_PORT / MCP_PATH で上書きできます:
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_PORT=9000 \
MCP_PATH=/mcp \
uv run python -m novelai_image_mcp serve
URL¶
エンドポイントの完全な URL は次のとおりです:
http://${MCP_HOST}:${MCP_PORT}${MCP_PATH}
デフォルト: http://127.0.0.1:8000/mcp。
エージェントの設定¶
MCP クライアント設定 (mcpServers)¶
docker compose up --build (または他の HTTP デプロイ) の後、MCP ホストを http
タイプでその URL に向けます:
{
"mcpServers": {
"novelai-image-http": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer <MCP_AUTH_TOKEN>"
}
}
}
}
http://127.0.0.1:8000/mcp は自前でデプロイしたエンドポイント (例: TLS 終端の
リバースプロキシの背後にある https://mcp.example.com/mcp) に置き換えてください。
Authorization ヘッダーは NovelAI のトークンではありません: サーバーは自身の
NOVELAI_TOKEN で NovelAI と通信します。このヘッダーが意味を持つのは、サーバー側で
MCP_AUTH_TOKEN が設定されている場合だけで、その場合は一致させる必要があります
(Authorization: Bearer <MCP_AUTH_TOKEN>)。MCP_AUTH_TOKEN (および MCP_ROUTE_TOKENS)
がない場合、エンドポイントは未認証のクライアントを受け付けます — TLS とリバース
プロキシの背後に置くか、MCP_HOST を localhost のままにしてください。
自作の Python エージェント¶
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([t.name for t in tools])
asyncio.run(main())
Curl (デバッグ)¶
streamable-http トランスポートはサーバー → クライアントのメッセージに Server-Sent Events を使います。サーバーを確認するための生の HTTP リクエスト:
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
Insiders ヘッダーとルーティング¶
opt-in ヘッダーを運べるのは HTTP だけなので、ルーティングのサーフェスはここにあります。
クライアントは X-MCP-Insiders でリクエストごとに opt-in し、ルーティングヘッダーで
自身のルートを宣言します:
{
"mcpServers": {
"novelai-image-http": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer <MCP_AUTH_TOKEN>",
"X-MCP-Insiders": "true",
"X-MCP-Agent-ID": "team-a",
"X-MCP-Model": "nai-diffusion-5-full"
}
}
}
}
このヘッダーがあると、サーバーはルート (ここでは team-a) を解決し、生成画像を
<NOVELAI_OUTPUT_DIR>/team-a/ に書き込み、novelai_image_mcp.audit.team-a ロガーに
1 行を出力し、監査 JSONL に 1 レコードを追記します。ヘッダーがなければ何も変わりません
— スコープ付きディレクトリも監査ファイルもありません。
この opt-in は director_tool の実験的な emotion / emotion_level パラメーターも
ゲートします。opt-in がない状態でどちらかを渡すと ToolError で失敗します。
ヘッダーの文法、候補ヘッダーの一覧、監査レコードのフィールド、秘匿化のルール、 拡張ポイントについては Insiders ヘッダー、ルーティング、監査 を参照してください。
ルートに束縛されたトークン¶
MCP_AUTH_TOKEN は単一の静的トークンのままです。MCP_ROUTE_TOKENS はルートに
束縛されたトークンを追加するため、1 つのゲートウェイがチームごとに異なるシークレットを
渡せます:
MCP_AUTH_TOKEN=static-token
MCP_ROUTE_TOKENS='{"team-a":"token-for-team-a","team-b":"token-for-team-b"}'
ルートトークンはそのルートとして認証され、同じリクエストがルーティングヘッダーで
異なる ルートを宣言した場合は 401 で拒否されます。使用可能なルートを宣言しない
リクエストは受け入れられ、トークンのルートに帰属されます。fail-closed になるのは、
2 つの異なるルートが両方とも提示された場合だけです。どちらの設定もない場合、認証
ミドルウェアはインストールされず、エンドポイントは以前と同じように動作します。
Docker デプロイ¶
最も単純な本番デプロイ:
docker compose up --build
リポジトリルートの docker-compose.yml
が、streamable-http トランスポートを妥当なデフォルトで構成します:
services:
mcp:
build:
context: .
dockerfile: apps/server/Dockerfile
ports:
- "8000:8000"
environment:
MCP_TRANSPORT: streamable-http
MCP_HOST: 0.0.0.0
MCP_PORT: 8000
NOVELAI_OUTPUT_DIR: /app/outputs
volumes:
- novelai-outputs:/app/outputs
ヘルスチェックはバインドポート (デフォルト 8000) を 30 秒ごとに確認します。
本番チェックリスト¶
警告
トランスポート自体は認証を提供しません。 MCP_AUTH_TOKEN (および
MCP_ROUTE_TOKENS) は MCP エンドポイントの手前にベアラー検証を追加しますが、
それは単一の共有シークレットであり、ID プロバイダーではありません — さらに
ルーティングヘッダーはクライアントが送るもので偽装可能です。サーバーをインターネットに
公開する前に、以下を前に置いてください:
TLS 終端 (Caddy、nginx、Traefik、AWS ALB)
認証レイヤー (mTLS、OAuth プロキシ、API ゲートウェイ)
レートリミッター (Anlas の濫用を防ぐため)
Tip
ローカルでのマルチクライアント利用なら localhost にバインドします。 同じマシン上の
複数のエージェント (例: Python と Node のエージェント) だけが必要なら、
MCP_HOST=127.0.0.1 を設定して TLS を省略します。リバースプロキシはネットワーク境界を
越える場合にのみ使ってください。
出力ディレクトリ
Docker では NOVELAI_OUTPUT_DIR=/app/outputs が名前付きボリューム
(novelai-outputs) で裏付けられています。生成画像はコンテナの再起動をまたいで
保持されます。Kubernetes では、ボリュームを PersistentVolumeClaim に置き換えてください。
同時実行モデル¶
サーバーは単一の共有
httpx.AsyncClient(コネクションプール) を使います。 複数の同時ツール呼び出しがプールを共有するため、リクエストごとの HTTP オーバーヘッドは ありません。各 MCP リクエストはサーバーのイベントループ上の独自の asyncio タスクで実行されます。
サーバーはリクエストをキューに入れたりレート制限したりしません — それは上流の プロキシの責務です。