MCP 連携

MCP 連携を利用すると、外部のエージェントから Agentino に接続して AOP の作成や実行を指示できます。 このページでは、MCP 連携に必要な認証設定の手順や、呼び出し可能なツールの一覧を説明します。

MCP 連携の仕組み

Agentino は、MCP（Model Context Protocol）のサーバーとして動作します。 外部のエージェントが MCP クライアントとして Agentino に接続すると、Agentino の機能をツールとして呼び出せます。

これにより、外部のエージェントから Agentino の AOP の読み取り、作成、コンパイル、実行、定期実行の管理、探索セッションの操作を指示できます。 Agentino を、ほかのエージェントの道具として利用できるようになります。

認証

MCP 連携の認証には、API アカウント機能で発行した API キーを使います。 外部のエージェントは、API キーを MCP クライアントの設定に登録して、Agentino の MCP サーバーに接続します。

API キーのスコープによって、MCP 経由で呼び出せる機能が決まります。 execute スコープを持つキーのみが、コンパイルと実行を呼び出せます。

接続の手順

接続は、API キーの発行と、MCP クライアントへの登録の 2 段階で行います。

1. Agentino のサービスアカウント画面で API キーを発行します
2. 発行した API キーと接続先 URL を、お使いの MCP クライアントに登録します

サービスアカウント画面には、発行したキーと接続先 URL を埋め込んだ接続コマンドがそのまま表示されます。 API キーは発行時に一度しか表示されないため、控えたうえで登録してください。

接続先 URL は共通で https://api-console.agentinos.app/mcp です。

以下の例では、API キーを <API キー> と表記します。 サービスアカウント画面に表示された値に置き換えてください。

Claude Code

コマンド 1 つで登録できます。

claude mcp add --transport http agentino https://api-console.agentinos.app/mcp --header "x-api-key: <API キー>"

Codex

Codex の codex mcp add は標準入出力型のサーバー向けで、HTTP 接続とカスタムヘッダーには対応していません。 設定ファイルを直接編集してください。

~/.codex/config.toml に次を追記します。

[mcp_servers.agentino]
url = "https://api-console.agentinos.app/mcp"
http_headers = { "x-api-key" = "<API キー>" }

API キーを設定ファイルに直接書きたくない場合は、環境変数から読ませられます。 次の書き方では、環境変数 AGENTINO_API_KEY の値がヘッダーに入ります。

[mcp_servers.agentino]
url = "https://api-console.agentinos.app/mcp"
env_http_headers = { "x-api-key" = "AGENTINO_API_KEY" }

プロジェクト単位で設定する場合は、プロジェクト直下の .codex/config.toml に同じ内容を書きます。

Cursor

すべてのプロジェクトで使う場合は ~/.cursor/mcp.json、特定のプロジェクトだけで使う場合はプロジェクト直下の .cursor/mcp.json に次を記述します。

{
  "mcpServers": {
    "agentino": {
      "url": "https://api-console.agentinos.app/mcp",
      "headers": {
        "x-api-key": "<API キー>"
      }
    }
  }
}

headers の値には環境変数を展開できます。 API キーを設定ファイルに直接書かない場合は、"x-api-key": "${env:AGENTINO_API_KEY}" の形にします。

そのほかの MCP クライアント

次の 3 点を設定します。

呼び出せるツールの一覧

MCP 経由で呼び出せるツールは次のとおりです。 呼び出せる範囲は API キーのスコープで決まります。

read スコープおよび write スコープは、すべてのキーが持ちます。 execute スコープは、明示的に付与したキーだけが持ちます。

コンパイルと実行は非同期で行われます。 compile_aop や start_run はジョブ ID や実行 ID を即時に返し、処理結果は get_compile_status や get_run_status で取得します。 実行中に人の承認が必要な操作が発生した場合は、Web 画面での対応を待つ状態になります。 コンパイルの進みの見方と止め方は、コンパイルの見方と止め方で説明します。

compile_aop は、AOP のコードがすでにあれば、今のコードの上に直しを積みます。 直しを積めないときは、コードを今のままにして、ジョブを失敗の状態にし、理由を stack（呼ばれる AOP を積めなかったときは sub_stacks）に入れて返します。 自動では作り直しません。 作り直すと前のコンパイルで直った所が戻ることがあるため、作り直すかは利用者が選びます。 作り直すときは、rebuild を真にして compile_aop を呼び直します。 コンパイルの間に同じ AOP のコードが別の保存で変わったために積めなかったときは、rebuild を付けずに呼び直すと、新しいコードの上に積みます。 AOP の直しがコードに届かなかった（直したフェーズのコードが、番号の付け替えのほかは変わらなかった、単段業務ではコードの全体が変わらなかったなど）ために積めなかったときは、rebuild を付けずに呼び直すと、もう一度積みます（積み直すか作り直すかは、利用者が選びます）。 積む仕組みと、機械で確かめる範囲はAOP の基本構造で説明しています。

外部エージェントの利用例

外部のエージェント（Claude Code や Cursor など）の MCP クライアント設定に、Agentino の MCP サーバーの URL と API キーを登録すると、そのエージェントから Agentino の機能を呼び出せるようになります。

これにより、外部エージェントは AOP を読み取り、コンパイルし、実行して結果を報告する一連の操作を自律的に行えます。

成功したコンパイルの報告

Agentino は、成功したコンパイルのジョブに、前の版のコードと比べた報告を付けます。 get_compile_status は、報告を report に入れて返します。 外部のエージェントは、報告を読めば、コードの全文を読まずに、どのフェーズが変わったかと、新しいコードがフェーズごとに何をするかが分かります。 AOP を直してコンパイルし直したときに、直したとおりにコードが変わったかを確かめるのに使えます。

報告に入るもの

報告は、コンパイルの後のコードを、前の版のコードと比べて作ります。 比べた 2 つの版の番号は、previous_generation_seq と new_generation_seq に入ります（read_generated_code が返す generation_seq と同じ数え方の番号です）。 報告には、次の 3 つが入ります。

• stages：AOP のフェーズごとに、前の版から変わったか（changed）、変わっていないか（unchanged）、足したか（added）、消したか（removed）を、フェーズの番号と名前で示します
• diff：変わったフェーズと、どのフェーズにも属さない所の、前の版と新しい版のコードの行の違いです（unified diff の形）
• summary：新しいコードが、フェーズごとに何をするかの要約です

unchanged は、フェーズのコードが、番号の付け替えと、前のフェーズの成果物を読む所のつなぎ直しのほかは、前と 1 文字も違わないことを表します。 どのフェーズにも属さない所（フェーズどうしをつなぐ部分など）が変わったかは、outside_changed が表します。

要約（summary）は、AI が書いた文章ではなく、新しいコードを Agentino が機械で読んだものです。 フェーズごとの phases に、使う道具とサービス（tools）、AI に考えさせるか（uses_ai）とその AI の役（ai_roles）、呼び出す別の AOP（sub_aops）が入ります。 接続先のサービス（MCP と HTTP API）と、コードの囲みの中の文を接続先にそのまま渡す専用の道具は、どのサービスの、どのカテゴリの機能を、読みだけで使うかまで出ます。 ブラウザや作業用サンドボックス、承認ゲートなども、道具として出ます。 どのフェーズにも属さない所で使う道具は、outside に入ります。 機械で読めなかった項目は、推し量らずに、そのフェーズの unreadable に理由を書きます。

報告の読み方

report を持たない成功のジョブは、この欄が加わる前に処理されたもので、変わった所が無いことを表すものではありません。 report の status が failed のときは、報告を返せなかったことを表し、理由の種類が reason に入ります。

• build_error：報告を作る途中で誤りが起きました
• input_too_large：新しい版か前の版のコードの字数が上限を越えたので、比べず、要約も読みませんでした
• too_large：返りの全体が大きすぎて、報告を縮めても収まりませんでした
• not_saved：呼ばれる AOP の報告にだけ付き、コンパイルの間にその AOP が消されたので、その AOP の新しいコードを保存していないことを表します

どの理由でも、ジョブは成功のままです。 not_saved のほかは、ジョブのコンパイルとコードの保存は成功していて、報告を返せなかっただけです。 input_too_large と too_large の報告も、2 つの版の番号（previous_generation_seq と new_generation_seq）を持ちます（前の版が無いか読めなかったときの previous_generation_seq は null です）。 too_large の報告は、さらに previous と changed と、変わったフェーズの数（changed_stage_count）を持ちます（前の版と比べなかったときの changed_stage_count は null です）。

報告が前の版と比べたものかは、previous で分かります。

• compared：前の版と比べました
• none：前の版が無い、初めてのコンパイルです
• unreadable：前の版のコードを読めませんでした

none と unreadable のときは、変わったフェーズの一覧（stages）が空で、差分（diff）と changed は null です。 どちらのときも、変わった所が無いことを表すものではありません。

compared のときは、何かが変わったかを changed が表します。 changed が偽なら、stages のどのフェーズも unchanged で、どのフェーズにも属さない所も変わっていません。 新しいコードを作らなかったコンパイルでは、今のコードを前と後の両方に置いて比べるので、2 つの版の番号が同じになり、changed は偽になります。

AOP の一部のフェーズを直してコンパイルし直したときに、直したフェーズだけが changed で、ほかのフェーズが unchanged なら、直したフェーズのほかはコードが変わっていないと分かります。 AOP の全文からコードを作り直したときは、直していないフェーズも changed になることがあるので、変わったフェーズを一覧で見て、要るなら差分で確かめます。

前と今のフェーズは、AOP のフェーズの名前で結びます。 AOP のフェーズの見出しが読めないときのように、名前で結べないときは番号で結び、matched_by が number になって、フェーズの名前は null になります。 番号で結んだときにフェーズを足したり消したりしていると、後ろのフェーズは同じ番号の別のフェーズと比べられるので、直していないフェーズも changed、added、removed と出ることがあります。 名前で結べても番号を付け替えられなかったときは、matched_by が name_without_renumbering になり、番号が変わったフェーズは、番号の違いだけでも changed と出ます。 単段業務のようにフェーズに分かれていない業務や、コードをフェーズに分けて読めないときは、業務の全体を 1 つとして比べ、その形を layout が表します。 このときは stages が空で、業務の全体が変わったかを changed が表します。

差分と要約が切られるとき

差分と要約には、上限の字数があります。 差分は、フェーズの順に、上限まで入れます。 上限に当たると、diff の truncated が真になり、差分を全部は入れられなかったフェーズ（どのフェーズにも属さない所を含みます）が omitted に並びます。 途中までを入れた差分は、その差分の cut が真になります。 要約は、上限を越えると、どのフェーズにも属さない所の細目を、次に後ろのフェーズの細目を落とし、落とした所を summary の trimmed に並べます。 細目を全部落としても越えるときは、後ろのフェーズから順にフェーズごと phases から外し、外したフェーズを、番号の小さい順に summary の omitted に並べます。 変わったフェーズの一覧（stages）は、この上限では切りません。 新しいコードの全文は、read_generated_code で読めます。

get_compile_status の返りの全体が大きくなりすぎるときは、報告をさらに縮めます。 縮める手は、次の順に当てます。

1. changed が偽の報告の、stages の行を省く
2. ほかの報告の stages から、unchanged の行を省く
3. 差分を後ろのフェーズから落とし、落としたフェーズを diff の omitted に並べる
4. 差分が 1 つも残らなかった報告の、diff の omitted を空にする
5. 要約の細目を、どのフェーズにも属さない所から、次に後ろのフェーズから落とし、落とした所を summary の trimmed に並べる
6. 全部のフェーズの細目を落とした報告の、summary の phases と omitted を空にし、trimmed からフェーズの項目を省く

1 つの手を、後に並ぶ呼ばれる AOP の報告から report まで、全部の報告に当ててから次の手に進み、返りが収まった所で止めます。 縮めた報告は shrunk を持ち、省いた stages の行の数、落とした差分の数、細目を落とした所の数などが入ります。 6 つの手を当てても収まらなければ、後に並ぶ呼ばれる AOP の報告から順に、status が failed、reason が too_large の報告に替えます。 stages の changed、added、removed の行は、報告を替えるまで省きません。

別の AOP を呼ぶ AOP の報告

別の AOP を呼ぶ AOP のジョブは、呼ばれる AOP ごとの報告を sub_reports に入れて返します。 sub_reports には、呼ばれる AOP の slug ごとに、report と同じ形の報告が入ります。 このコンパイルでコンパイルし直さなかった呼ばれる AOP の報告は、今の版を前と後の両方に置くので、変わった所が無いと出ます。 差分と要約の上限の字数は、report と sub_reports の全部で分け合い、report から順に使います。 そのため、後に並ぶ呼ばれる AOP の報告ほど、差分と要約が切られやすくなります。 前に並ぶ報告が要約の上限の字数を使い切っていたときは、要約を読まず、summary が null になります。

コンパイルの見方と止め方

MCP 経由で開始したコンパイルは、get_compile_status と list_compiles で進みを見て、cancel_compile で止められます。

進みの見方

コンパイルでは、AI モデルがコードを生成し、Agentino がそのコードを検証します。 検証に通らなければ、Agentino は理由を添えて生成し直させます。 生成と検証は、最初の 1 回を含めて、最大 3 回まで行います。

get_compile_status は、コンパイルの進みを次の値で返します。

• attempt：何回目の生成か（1〜3）。まだ始まっていないジョブでは null
• last_moved_at：コンパイルが最後に次の段階（コードの生成や検証など）へ進んだ時刻。実行中のときだけ値を持つ
• sub_aop：呼んでいる別の AOP をコンパイルしている間だけ、その AOP の名前を持つ。この間の attempt は、その AOP のコンパイルの何回目の生成かを表す
• stalled：最後に次の段階へ進んでから 10 分を越えたときだけ現れる知らせ。idle_minutes に進んでいない分数を、attempt に何回目の生成かを持つ
• elapsed_sec：終わったジョブで、処理を始めてから終わるまでにかかった時間（秒）。最初からやり直したジョブでは、やり直してからの時間
• restarted：Agentino のサービスの更新や障害で処理が中断され、コンパイルを最初からやり直した回数

list_compiles も、1 件ごとに attempt、last_moved_at、stalled、end_reason を返します。

stalled が現れても、コンパイルが詰まったとは限りません。 AI モデルがコードを生成している間は、生成が終わるまで次の段階へ進まないため、長いコードを生成しているときにも現れます。 stalled が現れている間も状態は running のままで、次の段階へ進むと stalled は消えます。 待つか止めるかは、stalled が示す長さと何回目の生成かを見て決めてください。 待つときは、状態を読み続けます。 止めるときは、cancel_compile で止めてから、必要なら compile_aop で開始し直します。

時間の上限

Agentino は、時間の上限を越えたコンパイルを、その時点で終えます。 上限は次の 2 つです。

• 1 回の生成と検証：30 分
• コンパイルの全体：90 分

全体の 90 分は、処理を始めた時から数え、待っている間（queued）は数えません。 呼んでいる別の AOP のコンパイルも、全体の 90 分に含みます。 処理が中断されて最初からやり直したときは、attempt と全体の時間を、やり直した時から数え直します。

上限を越えて終えたコンパイルは、新しいコードを保存せず、状態が failed になります。 Agentino は、自動ではコンパイルを開始し直しません。

止め方

要らなくなったコンパイルは、cancel_compile にジョブ ID を渡して止めます。 待っているコンパイルは、その場で終わり、後から始まりません。 実行中のコンパイルも、停止を受け付けた時点で終わり、新しいコードを保存しません。 止めたときの返り値の mode は cancelled です。

停止したコンパイルの状態は failed になりますが、停止は失敗とは違います。 状態が failed でも、end_reason が cancelled のジョブは、開始し直す必要はありません。

停止を受け付ける前に終わっていたコンパイルは、そのまま残ります（成功していれば、保存したコードもそのままです）。 このとき cancel_compile はエラーを返さず、mode を already_ended にして、その終わり方を note で伝えます。

止めたコンパイルの数には、組織ごとの上限があります。 API キーが属する組織で、直近 1 時間に cancel_compile で止めたコンパイルが 10 本に達している間は、compile_aop は新しいコンパイルを開始せずにエラーを返し、開始し直せる時刻を伝えます。 止めた結果この数に達したときは、cancel_compile の note も、開始し直せる時刻を伝えます。 この間も、cancel_compile でコンパイルを止めることはできます。 時間の上限を越えて終わったコンパイルは、この数に入りません。

同じ AOP のコンパイルが重なるとき

同じ AOP のコンパイルが待っているか実行中のときに compile_aop を呼ぶと、Agentino は新しいコンパイルを開始せずに、エラーを返します。 エラーには、そのコンパイルのジョブ ID と受け付けた時刻が入り、実行中のコンパイルなら、何回目の生成かと、最後に次の段階へ進んだ時刻も入ります。 そのコンパイルを待つか、cancel_compile で止めてから開始し直すかを選んでください。 停止したコンパイルは、待っているものにも実行中のものにも数えないため、止めた後はすぐに開始し直せます（止めたコンパイルの数が、上の「止め方」で説明した上限に達している間を除きます）。

ただし、処理を始めてから（始まっていなければ受け付けてから）5 時間を過ぎても終わっていないコンパイルは、途中で止まったまま残ったものとみなします。 Agentino は、compile_aop、get_compile_status、list_compiles が呼ばれたときに、そのコンパイルを interrupted で終えます。 compile_aop のときは、終えてから新しいコンパイルを開始します。

終わった理由の見方

failed になったジョブは、終わった理由を end_reason に持ちます（終わっていないジョブと成功したジョブでは null です）。 主な値は次のとおりです。

• cancelled：停止した
• timed_out：時間の上限を越えた
• response_unusable：AI モデルの応答が使えなかった（空だった、一度に書ける長さの上限で切れた、決まった形で読めなかった）
• transport_failed：AI モデルとの通信が続けて失敗した
• interrupted：処理が途中で止まり、完了しないまま中断した

このほかにも値があり（生成したコードが検証に通らなかったときなど）、error の文が理由を伝えます。 Agentino の内部で想定外のエラーが起きたとき（internal_error）は、error は内部エラーで失敗したことだけを伝えます。

AI モデルとの通信は、1 回失敗しただけではコンパイルを終えず、同じ生成をやり直します。 応答が空だったときや読めなかったときは、AOP を直さずに、同じ指定で開始し直せます。 一度に書ける長さの上限で切れたときは、AOP か、その直しが大きすぎる可能性があります。 時間の上限を越えたときと、通信が続けて失敗したときは、開始し直すかを呼び出す側で決めてください。 通信の失敗のあとに開始し直すときは、時間を置いてから呼び出します。

扱える範囲と記録の保持

list_compiles、get_compile_status、cancel_compile で扱えるのは、API キーの接続先のプロジェクトで、MCP 経由で開始したコンパイルだけです。 ほかのプロジェクトのジョブ ID は、見つからないとして扱います。 ビルダーエージェントで開始したコンパイルは、一覧に出ず、MCP から止めることもできません。 compile_aop が同じ AOP のコンパイルを確かめるときも、ビルダーエージェントで開始したコンパイルは数えません。

MCP 経由で開始したコンパイルの記録は、終わってから 24 時間を過ぎても、get_compile_status で読め、list_compiles にも出ます。

関連ページ

• API アカウント機能
• エージェント機能
• 実行の仕組み