warp-ozbridge

@sena-labs/oz-mcp-server

Warp™ Oz™ エージェント向けのスタンドアロンなModel Context Protocolサーバーです。VS Code は不要です。ターミナルから起動し、Claude Code、Cursor、Codex、または任意の MCP クライアントから Oz を操作できます。

OzBridge は独立したプロジェクトであり、Warp との提携、推奨、後援を受けていません。「Warp」と「Oz」は Warp, Inc. の商標であり、ここでは記述的に、相互運用性を説明する目的でのみ使用しています。以下の商標と免責事項をご覧ください。

このパッケージは、OzBridge 拡張機能から VS Code を取り除いた姉妹版です。同じ MCP ツール群（6 つのツール：oz_agent_run、oz_run_list、…）を stdio または Streamable HTTP 経由で提供するため、任意の MCP クライアントから Oz の実行を開始して確認できます。

---

要件

• Node.js ≥ 22.12
• Oz CLI がインストールされ、PATH に設定されていること（または OZ_PATH で指定されていること）。Warp は https://www.warp.dev/download からダウンロードしてください。oz コマンドは Warp に同梱されています（Linux の場合、通常は ~/.warp/bin/oz にあります）。oz --version で確認してください。
• Warp にサインインしていること。ターミナルで一度 oz login を実行してください。

このサーバーは、ドキュメント化された oz CLI を呼び出すだけです。Warp ソフトウェアを埋め込んだり、変更したり、リバースエンジニアリングしたりすることはありません。

---

クイックスタート（stdio — 推奨）

MCP クライアントから stdio 経由でサーバーを起動できます。インストールやポート、トークンは不要で、ターミナルを開いたままにしておく必要もありません。

Claude Code:

claude mcp add oz -- npx -y @sena-labs/oz-mcp-server --stdio

Codex CLI — ~/.codex/config.toml に追加します。

[mcp_servers.oz]
command = "npx"
args = ["-y", "@sena-labs/oz-mcp-server", "--stdio"]

Cursor / Windsurf / Claude Desktop — ~/.cursor/mcp.json（Cursor）、~/.codeium/windsurf/mcp_config.json（Windsurf）、または claude_desktop_config.json（Claude Desktop）に追加します。

{
  "mcpServers": {
    "oz": {
      "command": "npx",
      "args": ["-y", "@sena-labs/oz-mcp-server", "--stdio"]
    }
  }
}

HTTP モード

代わりに、クライアントが URL 経由で接続する長時間稼働のサーバーを起動するには、次のようにします。

npx -y @sena-labs/oz-mcp-server

127.0.0.1:3847 にバインドします。サーバーを起動したままにし、MCP クライアントから Streamable HTTP エンドポイント http://127.0.0.1:3847/mcp に接続してください。詳しくはMCP クライアントの設定（HTTP）をご覧ください。従来の HTTP+SSE エンドポイント /sse も引き続き提供されていますが、非推奨です。

デフォルト値の代わりにポートとベアラートークンを指定するには、次のようにします。

npx -y @sena-labs/oz-mcp-server --port 3847 --token my-secret

実行するたびに再ダウンロードしたくない場合は、グローバルにインストールできます。

npm install -g @sena-labs/oz-mcp-server
oz-mcp-server --help

---

設定

設定は次の順序で解決されます（上ほど優先度が高くなります）。

1. CLI フラグ
2. 環境変数
3. ./.warp/warp-bridge.yaml（現在の作業ディレクトリ）、次に ~/.warp/warp-bridge.yaml
4. コンパイル時のデフォルト値

CLI フラグ

フラグ	デフォルト	用途
--port <n>	3847	リッスンする TCP ポートです。0 を指定すると、OS が一時ポートを選択します。
--bind <addr>	127.0.0.1	バインドするインターフェースです。ループバック以外にバインドするには、トークンが必須です（セキュリティを参照）。
--token <s>	(なし)	すべてのリクエストで必要となるベアラートークンです。空の場合は認証なしです。
--cwd <dir>	process.cwd()	.warp/warp-bridge.yaml を検索するワークスペースのルートです。
--help, -h	—	使用方法を表示して終了します。

環境変数

変数	対応先	デフォルト	用途
OZ_PATH	ozPath	oz	Oz CLI バイナリへのパスです。裸の oz は PATH から解決されます。
OZ_MCP_PORT	port	3847	リッスンするポートです。0 = OS が割り当てる一時ポートです。
OZ_MCP_BIND	bind address	127.0.0.1	バインドするインターフェースです（デフォルトではループバックのみ）。
OZ_MCP_TOKEN	bearer token	(empty)	すべてのリクエストで必要なベアラートークンです。空の場合、認証は無効になります。
OZ_DEFAULT_MODEL	defaultModel	auto	実行時のデフォルト AI モデルです。
OZ_DEFAULT_PROFILE	defaultProfile	Default	デフォルトの Oz エージェントプロファイルです。
OZ_DEFAULT_ENV	defaultEnvironment	(empty)	デフォルトのクラウド環境 ID です。
OZ_TIMEOUT_MS	local run timeout	300000	ローカル実行のハードタイムアウト（ミリ秒）です。
OZ_IDLE_TIMEOUT_MS	idle timeout	90000	CLI の出力がない状態がこの時間続くと実行を中止します（ミリ秒）。0 にすると無効になります。

OZ_PATH=/usr/local/bin/oz \
OZ_MCP_PORT=3847 \
OZ_MCP_TOKEN=my-secret \
npx -y @sena-labs/oz-mcp-server

Windows PowerShell では、まず $env: を使って変数を設定します。

$env:OZ_MCP_TOKEN = "my-secret"; npx -y @sena-labs/oz-mcp-server

---

トランスポート

サーバーは、2 種類のトランスポートで MCP 通信を行います。

• stdio（--stdio）— ホストがサーバーを子プロセスとして起動し、stdin/stdout を介して JSON-RPC をやり取りします。Claude Code、Codex、 Cursor、Windsurf、Claude Desktop、mcp-proxy、レジストリのサンドボックス（例： Glama）での使用を推奨します。ポートもトークンも不要です。クイックスタートを参照してください。
• Streamable HTTP（--stdio を指定しない場合のデフォルト）— サーバーが ポートをリッスンし、クライアントは /mcp の URL に接続します。従来の HTTP + SSE トランスポート（/sse + /messages）もレガシー クライアント向けに引き続き提供されますが、非推奨です。

# stdio (spawned by the host)
npx -y @sena-labs/oz-mcp-server --stdio

# HTTP (default) — endpoint http://127.0.0.1:3847/mcp
npx -y @sena-labs/oz-mcp-server --port 3847

MCP クライアントの設定（HTTP）

URL ベースのクライアントでは、上記の HTTP モードでサーバーを起動し、 エンドポイントをクライアントに追加してください。以下のスニペットは docs/MCP.mdに準拠しています。

Claude Code

claude mcp add --transport http oz http://127.0.0.1:3847/mcp

Cursor / Windsurf

~/.cursor/mcp.json（または ~/.codeium/windsurf/mcp_config.json）に追加します。

{
  "mcpServers": {
    "oz": {
      "url": "http://127.0.0.1:3847/mcp"
    }
  }
}

Codex CLI

~/.codex/config.toml に追加します。

[mcp_servers.oz]
url = "http://127.0.0.1:3847/mcp"

トークンを設定した場合

--token / OZ_MCP_TOKEN を設定すると、すべてのリクエストに Authorization: Bearer <token> ヘッダーが必要です。

• Claude Code：claude mcp add に --header "Authorization: Bearer <token>" を追加します。
• Cursor / Windsurf："url" の隣に "headers": { "Authorization": "Bearer <token>" } を追加します。
• Codex：[mcp_servers.oz]の下にhttp_headers = { "Authorization" = "Bearer " }` を追加します。

---

公開されるツール

ツール	用途
oz_agent_run	プロンプトを指定して、ローカルで oz agent run を実行します。実行結果のペイロード全体を返します。
oz_agent_run_cloud	クラウド実行を開始します。Warp クレジットを消費します。
oz_run_get	ID で実行のステータスと出力を取得します。読み取り専用です。
oz_run_list	最近の実行を一覧表示します。all / active / completed / 生のステータスで絞り込み、数値の limit を指定できます。
oz_list_models	アカウントで利用可能な AI モデル ID を一覧表示し、現在のデフォルトを報告します。読み取り専用です。
oz_set_default_model	ワークスペースの .warp/warp-bridge.yaml に defaultModel を書き込み、デフォルトの Oz モデルを設定します。

各ツールの完全な JSON inputSchema は tools/list がそのまま出力します。 プロトコルの詳細、生の curl チートシート、エンドポイントのリファレンスについては、 docs/MCP.mdを参照してください。

エンドポイント

ルート	メソッド	目的
/mcp	POST	Streamable HTTP — 単一の JSON‑RPC 2.0 リクエストを受け取り、同じ HTTP レスポンスで応答します。こちらを使用してください。
/sse	GET	レガシー（非推奨）。 SSE ストリームを開きます。最初のフレームは、POST 先の sessionId を含む event: endpoint です。
/messages?sessionId=<uuid>	POST	レガシー（非推奨）。 単一の JSON‑RPC 2.0 リクエストです。202 で受理され、レスポンスは /sse 経由でストリーミングされます。
/health	GET	{ ok, name, version, tools, sessions } を返します。

ヘルスチェックをすばやく実行するには：

curl http://127.0.0.1:3847/health

---

セキュリティ

• デフォルトではループバックです。 サーバーは 127.0.0.1 にバインドされます。オプトインしない限り、トラフィックがマシンの外部に送信されることはありません。
• ループバック以外へのバインドにはトークンが必要です。 --token / OZ_MCP_TOKEN を指定せずに 127.0.0.1 / ::1 以外にバインドしようとすると拒否されます。MCP ツールの機能から Oz CLI を起動できるため、認証なしでパブリックにバインドすることはできません。
• トークンが設定されている場合、すべてのルートでベアラー認証が適用されます（/health を含む）。比較は定時間で行われます。
• 永続化はありません。 プロンプトの内容と実行出力は Oz CLI に転送され、サーバーには保存されません。

TLS 終端には対応していません。HTTPS が必要な場合は、認証済みのリバースプロキシの背後にサーバーを配置してください。

---

商標と免責事項

OzBridge は、Sena Labs の名称で Ivan Sena が開発する独立したプロジェクトです。Warp, Inc.、Microsoft、GitHub、または Visual Studio Code プロジェクトと提携、承認、後援、あるいは公式に関連しているものではありません。

Warp™ および Oz™ は Warp, Inc. の商標です。これらの名称は、OzBridge が Warp Oz と相互運用することを説明する目的に限り、このプロジェクトで記述的に使用されており、後援、承認、または提携を示唆するものではありません。

OzBridge は、oz コマンドラインツールと Model Context Protocol トランスポートという、Warp が公開している文書化済みのインターフェースのみを使用します。Warp のソフトウェアを改変、リバースエンジニアリング、組み込み、または派生物の作成をすることはなく、競合する製品やサービスではなく、補完的な連携機能です。

このソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。ご自身の責任でご使用ください。全文については DISCLAIMER.md をご覧ください。

---

ライセンス

MIT © Sena Labs