---
title: "MCPサーバー"
description: "Claude、ChatGPT、Cursor、VS Code、Codex、またはその他のMCPクライアントを、OAuthまたは個人アクセストークンでBeeuniに接続できます。1つのURLで、開くことのできるすべてのプロジェクトにアクセスできます。インストールは不要です。"
---

> **実験的機能です。** ツールは予告なく変更される場合があります。

Beeuni には、ホスト型 MCP サーバーが1つあります。

```text
https://api.beeuni.ai/v1/mcp
```

この URL を MCP クライアントに一度追加します。最初の呼び出し時に、ブラウザーで Beeuni へのサインインを求められます。その後、クライアントはあなたとして、あなたの権限で、アクセスできるすべてのアカウントとプロジェクトを操作します。これは [CLI](/docs/ja/cli) と同じ範囲です。URL にプロジェクト名は含まれません。ツールには `project_id` または `session_id` を渡し、`list_projects` で一覧を取得します。インストールは不要です。

<a id="add-it-to-a-client"></a>

## クライアントに追加する

以下の各クライアントは、手順にトークンの指定がない限り、初回使用時に OAuth でサインインします。置き換えるものはありません。プロジェクトごとに同じ URL を使います。

### Claude Code

```bash
claude mcp add --transport http beeuni https://api.beeuni.ai/v1/mcp
```

Claude Code で `/mcp` を実行してサインインします。代わりに個人用アクセストークンを使うには、コマンドに `--header "Authorization: Bearer $BEEUNI_TOKEN"` を追加します。

<a id="claude-desktop-and-claudeai"></a>

### Claude Desktop と claude.ai

**Settings → Connectors → Add custom connector** を選びます。URL を貼り付けてサインインします。

### ChatGPT

カスタム MCP コネクタを使うには、開発者モードが必要です。OpenAI の[開発者モードガイド](https://developers.openai.com/api/docs/guides/developer-mode) に従い、**Settings → Security and login** で **Developer mode** をオンにしてから、ChatGPT のプラグインページ（プラスボタン）で開発者モードのアプリを作成します。URL を入力し、認証方式に **OAuth** を選びます。利用できるプランやメニュー名は OpenAI のガイドに記載されていますが、変更される場合があります。表示名が異なる場合は、そのガイドを参照してください。

### Cursor

**Connect MCP** の **Add to Cursor** ボタンを使うか、すべてのプロジェクトで使う場合は `~/.cursor/mcp.json`、1つのプロジェクトで使う場合は `.cursor/mcp.json` にサーバーを追加します。

```json
{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp" } } }
```

### VS Code

サーバーを `.vscode/mcp.json` に追加します。VS Code では `mcpServers` ではなく `servers` を使い、`type` が必要です。

```json
{ "servers": { "beeuni": { "type": "http", "url": "https://api.beeuni.ai/v1/mcp" } } }
```

### Codex

```bash
codex mcp add beeuni --url https://api.beeuni.ai/v1/mcp
codex mcp login beeuni
```

または `~/.codex/config.toml` を編集します。個人用アクセストークンを使うには、トークンを格納する環境変数の名前を指定します。

```toml
[mcp_servers.beeuni]
url = "https://api.beeuni.ai/v1/mcp"
bearer_token_env_var = "BEEUNI_TOKEN"
```

<a id="other-clients"></a>

### その他のクライアント

URL を使って、リモート（Streamable HTTP）MCP サーバーを追加します。OAuth を実行できないクライアントでは、個人用アクセストークンをヘッダーとして送信します（下記参照）。

ワークスペースメニュー（左上のプロジェクト名）を開き、**Connect MCP** を選ぶと、URL と Claude、Claude Code、Cursor、Codex 用の手順をコピーできます。

<a id="sign-in"></a>

## サインイン

このサーバーは、MCP 仕様で定義されている OAuth 2.1 フローを使用します。クライアントは設定なしで処理します。

1. トークンなしの呼び出しには、`WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni"` を含む `401` が返されます。
2. クライアントは `/.well-known/oauth-protected-resource/v1/mcp` にある RFC 9728 ドキュメントを読み込みます。このドキュメントでは Beeuni が認可サーバーとして示されています。
3. クライアントは `POST /v1/oauth/register`（RFC 7591）で自身を登録します。PKCE のみで認証する公開クライアントが作成されます。
4. Beeuni の同意画面でクライアントを承認します。自己登録されたクライアントには、リダイレクト先のホストとともに **未確認アプリ** と表示されます。自分で接続するときに限り、承認してください。
5. クライアントはコードを交換して `beeuni_oat_` アクセストークン（有効期間1時間）とリフレッシュトークン（有効期間30日、使用時にローテーション）を取得します。アクセストークンが期限切れになると、クライアントが自動で更新するため、再度サインインする必要はありません。

<a id="revoke-a-client"></a>

### クライアントのアクセスを取り消す

**Settings → Personal access keys → Connected apps** には、すべてのアカウントで承認したアプリが一覧表示されます。アプリ名、サインイン先、最終アクティブ日時を確認できます。自己登録された MCP クライアントには **未確認アプリ** と表示されます。**アクセスを取り消す** と、承認が削除されてトークンが無効になります。次のリクエストは失敗し、再度承認を求められます。ターミナルからは、`beeuni tokens apps ls` と `beeuni tokens apps rm <client-id>` を使えます。どちらもブラウザーセッションまたは個人用アクセストークンからのみ実行でき、アプリ自身のトークンからは実行できません。

<a id="what-a-connected-app-cannot-do"></a>

### 接続アプリにできないこと

`beeuni` スコープは、あなたになり代わって動作します。つまり、接続アプリはあなたが読み取り・変更できるものを読み取り・変更できます。ただし、自身の無効化可能なトークンより長く有効な認証情報を作成することはできません。`beeuni_oat_` トークンでは、以下のルートは `403` を返します。

- 個人用アクセストークン（`POST /v1/accounts/tokens`）とプロジェクト CLI トークン
- ゲートウェイキー
- SCIM トークン
- OAuth クライアントと、そのシークレットのローテーション
- サービスアカウント
- 接続アプリの一覧とそのアクセス取り消し（`/v1/oauth/grants`）

クライアントのアクセスを取り消すと、そのアクセスは終了します。個人用アクセストークンはこれとは異なり、`--expires` を指定しない限り期限切れにならず、アプリのアクセスを取り消しても無効になりません。

<a id="personal-access-token"></a>

### 個人用アクセストークン

OAuth を使わないクライアントやスクリプトは、代わりに `beeuni_pat_` トークン（CLI が使用するトークン）を送信します。`beeuni tokens new <name>` を使うか、**Settings → Personal access keys** で作成し、ヘッダーとして送信します。

```json
{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp", "headers": { "Authorization": "Bearer beeuni_pat_…" } } } }
```

<a id="tools"></a>

## ツール

`tools/list` は23個のツールを返します。* が付いたパラメーターは必須です。

| ツール | パラメーター | 説明 |
| --- | --- | --- |
| `list_projects` | なし | すべてのアカウントで開けるプロジェクトを、`project_id`と自分のロールとともに一覧表示します。 |
| `start_session` | `project_id`*、`prompt`*、`name`、`agent` | 最初のプロンプトを指定して、プロジェクトでセッションを開始します。`session_id`を返します。 |
| `send_message` | `session_id`*、`text`* | セッションにメッセージをキューに追加し、停止中ならセッションを開始します。 |
| `read_session` | `session_id`*、`limit`、`wait_seconds` | セッションのステータス、ターンが`idle`、`booting`、`running`、`queued`のどれか、最新のメッセージと各ツール呼び出しの入力・出力を返します。`limit`はデフォルトで10、最大100です。`wait_seconds`（最大45）はターンが終了するまで待機します。 |
| `list_sessions` | `project_id`*、`limit`、`cursor` | プロジェクト内で表示できるセッションを一覧表示します。項目はID、タイトル、ステータス、エージェント、所有者、ブランチ、日付です。`limit`はデフォルトで20、最大200です。 |
| `run_command` | `session_id`*、`command`、`cwd`、`timeout_seconds`、`job_id`、`cancel` | セッションのサンドボックスでbashコマンドを実行し、stdout、stderr、終了コードを返します。長時間実行されるコマンドは、待機を続けるための`job_id`を返します。 |
| `read_file` | `path`*、`session_id`、`project_id`、`ref`、`offset`、`limit` | セッションのサンドボックス、または`ref`時点のプロジェクトのgitリポジトリからファイルを読み込みます。画像は画像として返します。 |
| `write_file` | `session_id`*、`path`*、`content`*、`encoding` | セッションのサンドボックスにファイルを書き込み、親ディレクトリを作成します。`encoding`は`utf8`（デフォルト）または`base64`です。 |
| `list_files` | `path`、`session_id`、`project_id`、`ref`、`offset` | セッションのサンドボックス内の1つのディレクトリ、または指定したパス配下にあるプロジェクトリポジトリのすべてのファイルを一覧表示します。 |
| `read_skill` | `name`、`file`、`project_id` | Beeuniプラットフォームのガイドを一覧表示するか、ガイド（`name`）またはその参照ファイル（`file`）を返します。`project_id`を指定すると、プロジェクト独自のスキルが最初に一覧表示されます。また、プロジェクトのスキル`name`は、その`SKILL.md`と参照ファイルのパスを返します。 |
| `list_connectors` | `project_id`*、`connector` | プロジェクトのコネクタを一覧表示します。項目はslug、プロバイダー、`connected`（現在利用可能かどうか）、アクション数、アカウントです。`connector`を指定すると、そのコネクタのアカウントをすべて一覧表示します。 |
| `search_connector_actions` | `project_id`*、`query`、`connector`、`limit` | 意図に基づいてコネクタのアクションを検索します。`tool`（`<connector>.<action>`）、`risk`、1行の説明を返します。スキーマは返しません。 |
| `describe_connector_action` | `project_id`*、`tool`* | 1つのアクションの入力JSON Schema、リスク、説明を返します。 |
| `call_connector` | `project_id`*、`tool`*、`args`、`account`、`reason` | 自分としてアクションを実行します。データと、実行した`account`、承認リンク付きの`pending_approval`結果、または理由付きの拒否を返します。 |
| `upload_connector_attachment` | `project_id`*、`connector`*、`filename`*、`content_base64`または`session_id` + `path` | ファイルをステージし、`args`に指定する`{"$beeuni_attachment": "<id>"}` refを返します。 |
| `connect_connector` | `project_id`*、`connector`*、`owner`、`label` | ユーザーが開いてコネクタのアカウントを接続するためのリンクを返します。 |
| `search_connector_apps` | `project_id`*、`query`*、`limit`、`cursor` | コネクタを追加できる、管理対象アプリのカタログを検索します。 |
| `add_connector` | `project_id`*、`app`または`provider` + `slug`、`name`、`url`、`transport`、`endpoint`、`spec`、`base_url` | コネクタをただちにプロジェクトに追加します（`main`上の`beeuni.yaml`にコミット後、同期）。 |
| `remove_connector` | `project_id`*、`connector`* | プロジェクトからコネクタを削除します。 |
| `beeuni` | `args`*、`project_id`、`session_id` | 実際の`beeuni` CLIを自分として実行し、`exit_code`、`stdout`（`--json`の出力では`json`）、`stderr`を返します。[任意のCLIコマンドを実行](#run-any-cli-command)を参照してください。 |
| `search_api` | `query`*、`limit` | Beeuni APIのルートをキーワードで検索します。 |
| `describe_api` | `method`*、`path`* | 1つのルートのパラメーター、リクエストボディ、レスポンススキーマを返します。 |
| `call_api` | `method`*、`path`*、`project_id`、`query`、`body` | 任意の`/v1/`ルートを自分として呼び出します。`project_id`はパス内の`{projectId}`を埋めます。 |

`search_api`、`describe_api`、`call_api`を使えば、Webアプリと[CLI](/docs/ja/cli)でできることをすべて実行できます。どちらも同じAPIのクライアントだからです。`call_api`は`/v1/oauth/*`と、MCPエンドポイントに到達するすべてのパスを拒否します。パス内の他の`{placeholder}`はすべて自分で指定してください。各呼び出しは、Webアプリからのリクエストと同じ認可と監査を受けます。APIはクライアントが送るラベルではなく、認証に使った認証情報を記録するため、監査ログには各呼び出しが`credential_kind: "oauth_app"`と接続済みアプリの名前とともに記録されます。

<a id="run-any-cli-command"></a>

### 任意のCLIコマンドを実行する

`beeuni`ツールは、実際の[`beeuni` CLI](/docs/ja/cli)を自分として実行します。すべてのCLIコマンドを実行できるため、MCPサーバーからはターミナルと同じ範囲にアクセスできます。secrets、triggers、`cr`、`review`、reminders、agents、models、gateway、providers、channels、sandboxes、apps、marketplace、files、access、roles、permissions、audit、grants、members、groups、tokens、billing、projects、sessions、`system-skills`が対象です。1つのツールで約200個のサブコマンドツールを置き換えられるため、Cursorなどのクライアントのツール上限を超えずに済みます。

`args`は`beeuni`以降のargvで、引数ごとに配列の要素を1つ使います。シェルのコマンドラインではありません。

```json
{ "name": "beeuni", "arguments": { "args": ["--help"] } }
{ "name": "beeuni", "arguments": { "args": ["secrets", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["triggers", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["system-skills"] } }
```

- `["--help"]`と`["<group>", "--help"]`で確認します。解析する出力には`--json`を指定してください。
- `project_id`はプロジェクト単位のコマンドのプロジェクトを指定します。`session_id`はセッションを対象とするコマンドのセッションを指定します。
- 結果はJSONです。`exit_code`、`stdout`、`stderr`。`--json`を指定すると、コマンドの出力は`stdout`ではなく、`json`内のJSON値として返されます。収まらない出力は切り詰められ、`truncated`が付けられます。切り詰められたJSONは有効なJSONではないため、コマンドの範囲を絞ってください。ゼロ以外の`exit_code`はMCPエラーです。各ストリームは文字数でstdoutが24,000、stderrが8,000で切り詰められ、`truncated`にその旨が記載されます。
- 約45秒を超えて実行されるコマンドは終了させられます。結果には`timed_out`が含まれます。
- サーバーが同時に実行するCLIコマンドは最大4つです。5つ目の呼び出しは`Busy`を返します。再試行してください。
- セッション、サンドボックス内のファイル、コネクタには専用ツール（`start_session`、`run_command`、`read_file`、`call_connector`）があります。これらを優先して使ってください。

CLIは、あなた自身のトークンを使って、このAPIに対しサーバー上で実行されます。サーバーの認証情報は渡されません。環境に含まれるのは、あなたのトークン、API URL、プロジェクトIDとセッションID、空の一時ホームディレクトリと作業ディレクトリだけです。コマンドの実行後、サーバーは両方を削除します。認可と監査はAPI側で行われます。外部ユーザーのトークンでも、ターミナルと同じ`403`を取得できます。

これらのコマンドは、実行前に拒否されます。エラーには理由と代替手段が示されます。

| コマンド | 理由 | 代わりに使うもの |
| --- | --- | --- |
| `--host`または`--host=`のフラグ、`hosts` | CLIの接続先サーバーを変更し、そこにトークンを送信します。 | このサーバーはすでにあなたとして動作しています。 |
| `login`、`logout` | ブラウザーでのサインインとトークンの保存。 | MCP接続を通じてサインイン済みです。 |
| `init`、`ship`、`deploy` | ローカルディレクトリの読み取りまたは書き込み。 | ソースがあるセッションサンドボックスで`run_command`を使います。 |
| `tools` | ローカルの`beeuni.yaml`を読み書きしますが、サーバーにはプロジェクトのチェックアウトがありません。 | セッションサンドボックスで`run_command`を使い、そこで`beeuni tools ls`を実行します。 |
| `apps deploy` | ローカルディレクトリをデプロイしますが、サーバーにはそのディレクトリがありません。 | セッションサンドボックスで`run_command`を使い、そこで`beeuni apps deploy <path>`を実行します。 |
| `env pull`、`env push` | ローカルファイルの書き込みまたは読み取り。 | `secrets ls`、`secrets set KEY=value`を使います。 |
| `token`、`whoami --token-only` | アクセストークンをそのまま出力します。 | `whoami --json`を使います。 |
| `update`、`uninstall` | CLIを実行するマシンを変更します。 | ありません。 |
| `tui`、`t`、`connect`、`attach`、`sessions connect|shell|forward` | 対話型ターミナルが必要です。 | `start_session`、`send_message`、`read_session`、`run_command`を使います。 |
| `chat`と`sessions chat`（`--prompt`なし） | 対話型チャットを開きます。 | `start_session`、`send_message`を使うか、`--prompt "<text>"`を追加します。 |

監査ログには、接続上の他のすべての呼び出しと同じ認証情報を使ったCLIコマンドが記録されます
（`credential_kind: "oauth_app"`）。`beeuni`ツールと`call_api`は区別できません。どちらもあなたのトークンを使ってAPIにアクセスします。

<a id="project-skills"></a>

### プロジェクトのスキル

`read_skill`に`project_id`を指定すると、プラットフォームガイドより先に、プロジェクト独自のスキル（リポジトリの`skills/<slug>/SKILL.md`ファイル、または旧式の`.beeuni/opencode/skills/`）が一覧表示されます。スキルの`name`を渡すと、その`SKILL.md`と参照ファイルのパスを読み取れます。参照ファイルを1つ読むには`file`を使います。自分のロールと許可で利用できるスキルが表示されます。

<a id="use-your-connectors"></a>

### コネクターを使う

コネクターツールは[`beeuni connectors`](/docs/ja/connect/connectors) CLIをMCPツールとして使います。CLIやSDKと同じAPIルートを呼び出すため、コネクターのポリシー、承認、監査の動作は、どのインターフェースでも同じです。

1. 接続中のものを確認するには`list_connectors`を使います。`connected: false`のコネクターではアクションを実行できません。`connect_connector`を呼び出し、返されたリンクを開いてから、再度一覧を取得してください。
2. アクションを目的から探すには`search_connector_actions`を使います。例：`send an email`。`describe_connector_action`は引数を返します。
3. 実行するには`call_connector`を使います。結果には、呼び出しを実行した`account`が示されます。アカウントが複数あり、デフォルトが設定されていないコネクターでは、`account`が必要です。
4. 引数がIDのみの書き込み（`send_draft`、IDによる削除など）では、`reason`を渡してください。承認者には、実際の引数と並んで表示されます。

ポリシーによって、呼び出しが承認待ちになることがあります。その場合、`call_connector`は`status: "pending_approval"`と`approval_url`を返します。担当者がリンクを開いて承認します。その後15分以内に、同じツール、引数、アカウントを指定して再度呼び出すと、承認された呼び出しが1回実行されます。`policy_block`による拒否は確定となります。

結果が約40,000文字を超える場合、マーカー付きのプレビューとして返されます（`data_truncated`）。引数を絞って再度呼び出してください。ファイルを添付するには、`upload_connector_attachment`でステージングし、返された参照を`args`に指定します。プロバイダーが`composio`のコネクターでは、添付ファイルの参照を受け付けません。

<a id="result-size-and-paging"></a>

### 結果のサイズとページ分割

- ツールの結果は60,000文字で切り詰められ、末尾に`…[truncated at 60000 chars]`が付きます。
- `read_file`は、長いテキストファイルを約50,000文字までのページに分けて返します。切り詰められた結果の末尾には、続きを取得するための`offset`が付きます。`offset`は行をスキップし、`limit`は返す行数の上限を設定します。バイナリファイルはテキストとして返されません。`run_command`で読み取ってください。
- `list_files`は長いリストを同様に切り詰めます。指定された`offset`を渡してください。
- セッションが残っている場合、`list_sessions`は`next_cursor`を返します。これを`cursor`として渡してください。
- `read_session`は最新の`limit`メッセージを返します。各ツールの入力と出力を切り詰め、結果に収まらない場合は古いメッセージを削除します（`omitted_older`）。失敗したターンは`last_turn_error`で示されます。
- 1回のMCPリクエストは55秒以内に応答します。`wait_seconds`を伴う`read_session`と、起動中のサンドボックスは、いずれもその前に停止します。再度呼び出してください。

<a id="sandboxes"></a>

### サンドボックス

`session_id`を指定して`run_command`、`read_file`、`write_file`、`list_files`を呼び出すと、セッションの稼働中のサンドボックスに接続します。Webターミナルやファイルパネルと同じです。相対パスは、セッションのGitチェックアウトである`/workspace`を基準に解決されます。停止中のサンドボックスは、最初の呼び出し時に起動します。サンドボックス内の`beeuni` CLIは、セッションとしてサインインしています。`project_id`があり、`session_id`がない場合、`read_file`と`list_files`はプロジェクトのGitリポジトリを読み取り、サンドボックスを起動しません。

コマンドは数分かかることがあります。1回のツール呼び出しで待機する時間は約50秒です。その時点でコマンドがまだ実行中の場合、`run_command`は`status: running`、`job_id`、それまでの出力を返します。その`job_id`を使って`run_command`を呼び出すと待機を続け、`cancel: true`を指定すると停止します。`timeout_seconds`（デフォルトは600、最大は86400）を超えて実行されたコマンドは、終了コード`124`で停止します。出力はサンドボックス内の`~/.cache/beeuni-mcp/jobs/<job_id>/`に保存されます。ツールの結果には、各ストリームの末尾24,000バイトが表示されます。サンドボックスが停止すると、実行中のコマンドも停止します。

サーバーはステートレスです。`POST`にはJSONで応答し、`GET`と`DELETE`には`405`で応答します。