Synap Memory

synap-mcp-server

ホスト型のリモート MCP サーバー（Streamable HTTP）です。既存の Synap パブリック REST 操作を MCP ツールとして再公開するため、ノーコードプラットフォーム（Gumloop、n8n）では、MCP URL と Bearer トークンを貼り付けるだけで、エージェントに永続的なメモリを持たせられます。

これはステートレスなアダプターです。新たなバックエンド、ストレージ、パイプラインはありません。各ツール呼び出しは既存の REST 操作 1 つに対応し、受信した Bearer synap_<key> トークンは、認証を担う synap-cloud にそのまま転送されます。

• パブリックエンドポイント（本番環境）：https://synap-mcp.maximem.ai/mcp
• ヘルスチェック：https://synap-mcp.maximem.ai/health

ツール

ツール	REST 操作	備考
log_exchange	POST /api/v1/memories/create (mode=long-range)	毎ターン転送してください。何を保持するかは抽出処理が判断します。user_id はエンドユーザーごとのスコープを指定し、customer_id は B2B 専用です（「スコープ設定」を参照）。conversation_id は任意です。
recall_context	POST /v1/context/{client|user|customer}/fetch (mode=fast)	ホットパスです。ID がない場合はクライアントスコープになります。customer スコープは B2B 専用です。
list_recent_memories	広範な /v1/context/.../fetch（クエリなし）	デバッグ／「メモリをテスト」。スコープのルールは同じです。
check_memory_status	GET /api/v1/memories/status/{id}	スコープ ID は不要です。ingestion_id がすでに書き込みを特定しています。

スコープ設定：1 つの契約、2 つのモード

REST API により、このルールは強制されます。推奨事項ではなく、2026-08-26 07:07 UTC 以降、本番環境で適用されています。

インスタンスモード（user_context_isolation）	送信する値	それ以外の場合
equals_customer（B2C）	user_id のみ。ユーザー ID がそのまま全体の識別子になります。	customer_id を指定すると、HTTP 400 で拒否されます。/v1/context/customer/fetch は利用できません。
strict（B2B）	user_id とともに customer_id が必須です。	user_id のみを指定するとエラーになります。この契約による変更はありません。

GET /api/v1/auth/whoami は、モードを user_context_isolation として返します。このサーバーはトークンごとに一度だけモードを読み取り、B2C インスタンスでは customer_id をローカルで拒否します。そのため、モデルには対処できないステータスコードではなく、代わりに何を送信すべきかを説明する文が返されます。モードを読み取れない場合は何も拒否せず、API が引き続き正規の判定元になります。

ID をまったく指定しないと、クライアントスコープ（認証情報ごとに共有）になります。これはどちらのモードでも有効です。注：クライアントスコープへの書き込みはダッシュボードの「Memories」ページ（リレーショナル）には表示されないため、ダッシュボードでの可視性が重要な場合はユーザースコープを推奨します。n8n の式または Gumloop の入力から user_id を設定し、log_exchange と recall_context の両方に同じ値を渡して、書き込みと読み取りが同じユーザーを参照するようにしてください。

Host ヘッダー。 サーバーは MCP トランスポートの DNS リバインディングチェックを無効にしています（プロキシの背後にあり、Bearer 認証を使用するため）。そのため、リバースプロキシから実際の Host を転送でき、Host を書き換えるハックは不要です。

ローカルで実行する

pip install -e ".[dev]"
SYNAP_API_URL=http://localhost:8000 uvicorn synap_mcp_server.server:app --port 8090
curl http://localhost:8090/health        # {"status":"ok",...}

予測エージェントへのターン報告

MCP サーバーはエージェントではありません。他者のエージェントにツールを公開し、ステートレスな HTTP 呼び出しを一度に 1 つ受け取るため、エージェントの処理の大部分はここからは見えません。呼び出し元によるツール呼び出し、その結果、推論がこのプロセスに届くことはなく、会話が終了したことをステートレスなサーバーに知らせるものもありません。報告する対象がないため、これらは報告されません。

ターン自体は存在します。log_exchange には、ユーザーのメッセージとアシスタントの返信が引数として渡されます。MCP_STREAM_EVENTS=true を設定すると、記録された各やり取りは POST /v1/events/batch に会話ターンとしても報告されます。これは、gRPC ストリームが利用するのと同じ待ち受け経路につながる HTTP の入口であり、予測エージェントは、そこから抽出されたメモリーだけでなくターンも確認できます。このサーバーは、他のインテグレーションとは異なり、SDK の gRPC ストリームを使用しません。SDK を保持せず、リクエスト間で状態を維持せず、リクエストごとに異なるテナントのキーが渡される場合もあるため、キーごとにストリームを作成すると、閉じるものが何もない接続が無制限に増えることになります。ストリームが返す情報を必要としない呼び出し元のために、SDK に移行するのはトランスポートの書き換えにあたります。

また、Synap の要約処理を置き換えるものでもありません。呼び出し元のエージェントは独自の履歴を保持し、このサーバーのツールが会話を返すことはありません。

意図的に、デフォルトでは無効です。有効にすると、log_exchange ごとにバックエンド呼び出しがもう 1 回追加され、長期保存用ドキュメントに加えて会話履歴にもターンが書き込まれ、予測エージェントが実行されます。その際、モデル呼び出しの料金が発生します。

デフォルトで有効にしない理由はもう 1 つあります。Synap は、メッセージが 10 件記録されると会話を要約し、そこから情報を抽出します。やり取りを長期保存用ドキュメントの代わりにターンとして記録すると、その時点までメモリーへの反映が保留されます（次の recall_context で何も見つからず、確認できる ingestion_id もありません）。一方、長期保存用ドキュメントと併せて記録すると、各やり取りから情報が 2 回抽出されます。

どちらの場合も変わらないこと：log_exchange は引き続き長期保存用ドキュメントをキューに追加し、check_memory_status と wait_for_processing が利用する ingestion_id を返します。ターンの報告はベストエフォートであり、ツールの回答が変わることはありません。user_id または conversation_id がないターンは、イベントのルートで両方が必須となるため、報告されません。

テスト

pip install -e ".[dev]"
pytest -q

設定（env）

変数	デフォルト	意味
SYNAP_API_URL	http://synap-cloud:8000	接続先 REST API のベース URL（本番環境では内部 Docker ホスト名）。
MCP_PORT	8090	待ち受けポート。
MCP_RECALL_TIMEOUT_S	10	想起（読み取り）のタイムアウト。
MCP_INGEST_TIMEOUT_S	8	記録／取り込み（書き込み）のタイムアウト。
MCP_DEFAULT_MAX_RESULTS	10	想起結果のデフォルト件数。
MCP_STREAM_EVENTS	false	記録したやり取りを、予測のための会話ターンとしても報告します。有効にする前に上記をご確認ください。
MCP_EVENTS_TIMEOUT_S	4	ターン報告のタイムアウト。ベストエフォートであり、報告に失敗してもツールの回答は変わりません。
LOG_LEVEL	INFO	ログレベル。
ENVIRONMENT	production	/health で報告される環境。

サーバーには Synap API キーを設定しません。エンドユーザーのキーは、リクエストごとに Bearer トークンとして渡されます。

プラットフォームのセットアップガイド（Gumloop、n8n）とデプロイの詳細については、Synap MCP のドキュメントをご覧ください。