# ヘッドレス環境から Beatra MCP に接続する
> エージェントが接続を開始し、利用者がスマートフォンや別のパソコンで承認します。

SSH サーバー、コンテナ、クラウド VM など、利用者のブラウザーを開けない環境で使う手順です。
ブラウザーを開ける MCP ホストでは、`https://mcp.beatra.cn/mcp` を追加し、ホストのログイン手順に従ってください。

## 接続する

Python 3.8 以降が必要です。追加パッケージは不要です。

```bash
mkdir -p ~/.beatra/connector
curl -fsSL https://api.beatra.cn/oauth/connector/connect.py -o ~/.beatra/connector/beatra_connect.py
python3 ~/.beatra/connector/beatra_connect.py --host claude-code
```

1. 最初の実行で `BEATRA_CONNECT_PENDING`、リンク、接続コードが表示されます。リンクとコードを利用者に伝えます。利用者は任意の端末でリンクを開き、Beatra にログインし、コードが一致することを確認して **許可** を選びます。
2. 同じコマンドをもう一度実行します。各実行は最大 90 秒待ちます。`BEATRA_CONNECT_READY` が表示されるまで繰り返します。接続コードの有効期限は 15 分で、期限切れの場合は次の実行で新しいコードが発行されます。
3. ホストの MCP サーバーを再読み込みし、無料の `beatra.tasks.list` を呼び出して確認します。

コマンドはトークンを表示しません。`*.token`、`*.pending.json`、書き込まれたホスト設定を表示・コピーしないでください。トークンをプロンプト、コマンドライン、プロジェクトファイルに入れないでください。

## ホストを選ぶ

| ホスト | `--host` | 設定と再読み込み |
| --- | --- | --- |
| Claude Code | `claude-code` | ユーザー設定の `beatra` とヘッダーヘルパー。`/mcp` で再接続、または再起動 |
| Codex | `codex` | `~/.codex/config.toml` の `[mcp_servers.beatra]`。新しいセッションを開始 |
| Cursor | `cursor` | `~/.cursor/mcp.json` の `beatra`。再起動またはウィンドウの再読み込み |
| JSON の `mcpServers` 設定を使うホスト | `json --config <path>` | プロジェクト設定ではなくユーザー設定を指定。ホストの手順で再読み込み |
| トークンファイルやヘッダーヘルパーを使うホスト | `file` | 非公開のファイルとヘルパーのパスを表示。ホストにそのパスを設定 |

実測した Grok Build 1.0.77 では、Beatra のツール名が拒否されるため、このネイティブ MCP 接続は利用できません。引き続き Beatra Skill を使用してください。

`--name "<アプリ名>"` で承認ページの表示名を指定できます。各マシンで個別に承認し、トークンファイルを別のマシンへコピーしないでください。

## 接続を解除する

コンソールの **デバイス → 接続済みアプリ**、または [接続済みアプリ](https://console.beatra.cn/apps) から解除できます。次の呼び出しは拒否されます。
再接続には同じコマンドを実行し、もう一度承認してください。このコマンドによる接続は、解除されるか、1 年間使われなくなるまで有効です。

中国本土では [中国向けの手順](https://docs.beatra.cn/zh/docs/agent-connect) を使ってください。`api.beatra.cn` から取得したスクリプトは `.cn` の接続先を使います。