Tooon MCP
エージェントと、ワークスペースを整理する。
CodexやClaude Codeから、Tooonの情報を読み取り、関係を図にして、整理の方針を考える。変更案を確認したら、そのままプロジェクトやタスクを更新できます。
- 01全体をつかむ
仕事とページを棚卸しする
- 02つながりを見る
エージェントが関係を図にする
- 03変更案を確かめる
対象と変更前後を見て決める
- 04確認した内容を反映する
現在の権限と更新状況を再確認する
接続の準備
Solo以上のプランで、ワークスペースの管理者がAPIキーを発行します。MCPは、使うエージェントにTooonの操作を伝える共通の接続方式です。
- ワークスペースを選ぶ
TooonのURLの
/workspaces/の直後がワークスペースIDです。プロジェクトIDではありません。 - 用途別のAPIキーを発行する
「設定 → 連携 → APIキー」で、名前と権限を選びます。棚卸しには「ページと構成の参照」と、プロジェクト・タスク・取引先など必要な項目の参照権限を選びます。
- エージェントに設定する
下の例の
<workspaceId>を置き換え、起動する環境にTOOON_API_KEYを設定します。キーをチャットや共有リポジトリに貼り付けないでください。
接続先は https://tooon.app/api/mcp/<workspaceId>。キーを発行したワークスペースだけを操作できます。Tooonにログインする
Codexで使う
Codexの設定ファイルにMCPサーバーを追加します。環境変数がCodexの起動プロセスから読み取れる状態で、接続を読み込み直してください。
tooon_apply_change は毎回確認する設定です。読み取りと変更プレビューの結果を見てから、実行するか決められます。
接続したら、tooon_capabilities でワークスペースIDと使える操作を確かめます。
[mcp_servers.tooon]
url = "https://tooon.app/api/mcp/<workspaceId>"
bearer_token_env_var = "TOOON_API_KEY"
default_tools_approval_mode = "writes"
tool_timeout_sec = 45
[mcp_servers.tooon.tools.tooon_apply_change]
approval_mode = "prompt"Claude Codeで使う
プロジェクトの .mcp.json に設定します。APIキーは環境変数から読み込むため、設定例の変数参照はそのまま残します。
Claude Codeの /mcp で接続状態を確認します。Tooon MCPは変更の適用を、人による確認が必要な操作として伝えます。対応するクライアントの確認設定も有効にしてください。
{
"mcpServers": {
"tooon": {
"type": "http",
"url": "https://tooon.app/api/mcp/<workspaceId>",
"headers": {
"Authorization": "Bearer ${TOOON_API_KEY}"
}
}
}
}まず、棚卸しと可視化から
プロジェクトとタスク、ページとデータベース、その参照関係を取得できます。MCPが返すIDを使って、エージェントが図や一覧にまとめます。
同じプロジェクトが複数のユニットに表示されることがあります。同じIDの表示先と、別のIDを持つ項目を分けて確認します。
全件を調べるときは一覧の続きを最後まで取得します。取得できない項目や権限のない範囲も、棚卸し結果に残してください。
このワークスペースを読み取りだけで棚卸ししてください。
プロジェクト、タスク、ページ、データベースの関係を図にし、
重複している可能性のある項目や、整理できそうな項目を挙げてください。
同じIDの表示先が複数あっても、重複とは数えないでください。
取得できた範囲と未取得の範囲を分け、変更はまだ行わないでください。変更案を確認してから、実行する
- 現在の内容を読む
更新対象のIDと
updatedAtを取得します。 - 変更案をつくる
tooon_preview_changeに操作名と入力を渡します。対象と変更前後が返り、この時点では保存されません。更新にはexpectedUpdatedAtが必要です。 - 確認した内容を反映する
本人が内容を確認したら、返された
previewTokenをtooon_apply_changeに渡します。案は5分間有効です。適用せずに破棄すれば、変更は行われません。
別の編集が入った場合は競合として止まります。新しい内容を読み、案を作り直してください。同じ案を再送しても、同じ変更を二重に反映しない仕組みです。
使えるツール
接続時に、キーの権限に合うツールだけが表示されます。入力の詳細は tooon_capabilities で取得できます。
- 接続と操作範囲
tooon_capabilities対象ワークスペース、利用できる操作、取得範囲を確認します。
- 業務データ
tooon_listProjects/tooon_listTasks/tooon_listClientsプロジェクト・タスク・取引先の一覧と詳細。権限に応じて、パートナー・請求・経費・会社の人や名刺なども参照できます。
- ページと関係
tooon_list_pages/tooon_get_page/tooon_page_navigationページ本文、データベース、表示位置を取得します。参照元・添付情報・プロジェクトとの関係を調べるツールもあります。
- 変更の確認と適用
tooon_preview_change/tooon_apply_changeプロジェクト・タスク・取引先を作成、更新します。状態や親子関係の変更も既存の業務ルールに従います。
書き込み操作名は createProject、updateProject、createTask、updateTask、createClient、updateClient です。
プロジェクトの状態 archivedは、現在の一覧では「保留」と表示されます。「完了」とは別の状態です。
権限と利用範囲
- APIキーの権限と、発行した管理者の現在の権限の両方を確認します。非公開ページやユニットの制限も引き継ぎます。
- ページ・データベースの参照は
work:read。業務データは領域ごとの:read、作成・更新は:writeが必要です。更新プレビューには同じ領域の参照権限も必要です。 - ページの移動・統合・削除、独立したファイルライブラリの全件取得、完全削除、請求の発行・外部送信・支払いは、この版では扱いません。
- 請求・契約とプロジェクトの関連は、一部のAPIで取得できません。整理する対象は、Tooonの画面でも関連を確認してください。
- 通常のワークスペースAPIキーで接続します。Tooon Connect用のキーとOAuthログインには対応していません。
- 通常APIと同じ、キーあたり毎分60回の制限を共有します。MCPのリクエストと内部のAPI呼び出しはそれぞれ数えます。本文は256 KiBまでです。
- サイドバーの一覧は表示用の一部です。棚卸しには各一覧の
nextCursor、ページ構成のnextId、データベース行のnextRowIdをたどります。
接続を止めるときは「設定 → 連携 → APIキー」で専用キーを無効にします。
接続できないとき
- 401 / 認証エラー
- 環境変数がエージェントの起動環境に渡っているか、キーが無効になっていないか確認します。
- 403 / 権限エラー
- URLのワークスペースID、キーの権限、発行者の現在の権限を確認します。権限のないツールは表示されません。
- 変更案が期限切れ・競合
- 現在の内容を再取得し、変更案を作り直します。
- 429 / 呼び出し上限
Retry-Afterの時間を待ち、取得できなかった一覧の続きから再開します。
自社システムから直接つなぐなら Tooon API、会員向けサービスに機能を届けるなら Tooon Connect をご覧ください。