メインコンテンツまでスキップ

AI クライアント接続ガイド(MCP)

MCP 対応の AI クライアントから、AGENTIC STAR の MCP につなぐ手順です。チャットの組のツールでは Agent に仕事を頼み、プロジェクトの組のツールでは登録 Agent でプロジェクトを作る・動かす・確認依頼を片付けるなどができます。ツールの詳しい仕様は MCP API リファレンス を参照してください。

始める前に

MCP は、管理者が MCP の受け口を開けた環境でだけ使えます。人が自分のアカウントでつなぐには、外部ツールでのログインの入口も開いている必要があります(API 利用準備ガイド)。

用意するもの​

  • 使う AI クライアント(Claude Code・Codex・Cursor・VS Code)
  • 人がつなぐとき: 管理者が認証サーバーのコンソールで作った、外部ツールのクライアントのクライアント ID
  • システム連携でつなぐとき: 管理者が管理画面で作ったサービスアカウント(クライアント ID・クライアントシークレット)
  • 環境の外部 API の入口の住所(<your-domain>)と、認証サーバーの外の入口の住所(<auth-domain>)

プラグインで入れる(おすすめ)​

Claude Code・Codex には、AGENTIC STAR のプラグインを入れられます。入れた後に「AGENTIC STAR につないで」と頼むと、つなぎ方を案内します。

入っているもの役割
agenticstar-connectAGENTIC STAR の MCP につなぐ手順を案内する
agenticstar-projects登録 Agent でプロジェクトを作る・失敗を調べる・確認依頼を片付ける・結果を読む
  • MCP の接続設定は入っていません。クライアント ID などは、案内に沿って設定します
  • SaaS版とは別のプラグインです。マーケットプレイス版ではこのページのプラグインを使ってください
  • 今の版: 3.2.0

プラグインをダウンロード(agenticstar-mp.zip)

zip を展開したフォルダで、次を実行します(Claude Code 2.1.292 以降)。

curl
claude plugin install agenticstar-mp --marketplace ./agenticstar-mp

つなぎ方を選ぶ​

使う人つなぎ方用意するもの
人(自分のアカウントで使う)クライアントでログインする外部ツールのクライアント(クライアント ID)
仕組み(システム連携)Client Credentials フローで取ったトークンを Authorization: Bearer に書くサービスアカウント(クライアント ID・クライアントシークレット)

MCP のエンドポイントは次のとおりです。使うツールの組を toolsets で選びます(ツールの組)。公開したワークフローも呼ぶときは published を足します。

https://<your-domain>/api/v1/mcp?toolsets=chat,project

外部ツールでは、使うスコープを選びません。人がつなぐときは、その人がメイン画面でできることを、外部ツールからもできます。

設定の例について

このページの設定は、参考のための例です。設定の方法は、クライアントの版によって変わることがあります。最新の方法は、各クライアントの文書を確認してください(Claude Code・Codex・Cursor・VS Code)。ほかの MCP クライアントでは、エンドポイントとクライアント ID を、そのクライアントの文書に沿って設定してください。

ドメインを設定していない環境で確かめるとき​

ドメインと証明書を設定していない環境(出荷時の状態)では、入口は製品が作った自己署名の証明書を使います。外部ツールはこの証明書を信じないので、そのままではつながりません。出荷時の状態でつながることを試すときは、次のようにします。ログインのときに開くブラウザでも、証明書の警告が出ます。

Claude Code​

証明書の確かめを切って起動します。

curl
NODE_TLS_REJECT_UNAUTHORIZED=0 claude

確かめを切ると、通信が盗み見られたり書き換えられたりしても気付けません。試す間だけ、その起動の中だけで使ってください。

Codex​

入口の証明書を取り出して、Codex に信じさせます。

  1. 入口の証明書をファイルに保存します(<your-domain> は外部 API の入口の住所)

    curl
    openssl s_client -connect <your-domain>:443 -showcerts < /dev/null | openssl x509 > agentic-star.crt
  2. 環境変数 CODEX_CA_CERTIFICATE に、保存したファイルのパスを入れてから Codex を起動します(codex mcp login の前に)

    curl
    export CODEX_CA_CERTIFICATE="$PWD/agentic-star.crt"

証明書は、作り直されると変わります(期限は 365 日です。外部ツールでのログインの入口を開けたときにも作り直されます)。つながらなくなったら、取り出し直してください。

Cursor・VS Code​

この状態ではつながりません。Cursor は「Connecting...」のまま理由を出さず、VS Code は unable to verify the first certificate と出します。ドメインと証明書を設定してから使ってください。

正式に運用を始める前に​

必ずドメインと証明書を設定してください。設定すれば、どちらの設定も要りません(ドメイン設定ガイド)。

人がつなぐ​

1. 外部ツールのクライアントを用意する​

管理者が、API 利用準備ガイド — 外部ツールのクライアントの作成手順 に沿って、認証サーバーのコンソールでクライアントを作ります。戻り先には http://localhost/callback と http://127.0.0.1/callback を登録します。VS Code を使うときは http://127.0.0.1/ も登録します。ポートは問われないので、下のクライアントで指定するポートは、空いているものを自由に選べます。

2. クライアントを設定してログインする​

<client_id> には、作ったクライアントのクライアント ID を入れます。

curl
claude mcp add --scope user --transport http \
--client-id <client_id> --callback-port <ポート> \
agenticstar 'https://<your-domain>/api/v1/mcp?toolsets=chat,project'

Claude Code の中で /mcp を開いて agenticstar の認証を選ぶか、claude mcp login agenticstar を実行すると、ブラウザでログインの画面が開きます。

システム連携でつなぐ​

  1. API 利用準備ガイド — システム連携の作成手順 に沿って、管理画面でサービスアカウントを作ります
  2. 認証ガイド — Client Credentials フロー で、https://<auth-domain>/api/v1/oauth/token からアクセストークンを取ります
  3. クライアントに Authorization: Bearer <access_token> を設定します。トークンの有効期限が切れたら、同じ手順で取り直して設定し直します(トークンの再取得)
curl
claude mcp add --scope user --transport http agenticstar-system \
'https://<your-domain>/api/v1/mcp?toolsets=chat,project' \
--header "Authorization: Bearer <access_token>"

システム連携で使えるのは、チャットの組のツール、プロジェクトの組の 4 つの操作(project_read の list・run_read の get・project_run の start_run・fire_trigger)、公開したツールの組のツールです。システム連携のトークンでは、この環境にあるすべてのプロジェクトを扱えます。

安全に使う​

  • 書き込む操作: プロジェクトを作る・変える・消す、確認依頼を決めるなどの操作を AI に任せるときは、クライアントの許可の仕組みで、実行の前に確かめられるようにしてください(Claude Code は、確認依頼を決める前に毎回許可を求めます。ほかのクライアントは、そのクライアントの文書を確認してください)
  • トークンとシークレット: アクセストークンとクライアントシークレットは、秘密の値として扱ってください。チャットや文書に貼らないでください
  • 外部ツールを止めるとき: ログインした外部ツールは、メイン画面からログアウトしても止まりません。止め方は API 利用準備ガイド — 外部ツールを止める を参照してください
  • 資格情報が漏れたとき: 管理画面でサービスアカウントを無効化するか、クライアントシークレットを作り直してください(API 利用準備ガイド — 資格情報が漏れたとき)

つながらないとき​

  • すべての呼び出しが 404: MCP の受け口か、外部ツールでのログインの入口が、この環境で開いていません。管理者に確かめてください
  • 証明書のエラー: ドメインを設定していない環境で確かめるとき を参照してください
  • ツールの組: toolsets を指定しないと、チャットの組だけになります。プロジェクトの組を使うときは project、公開したワークフローを呼ぶときは published を指定してください
  • ログインが断られる: 承認待ちのアカウントと、メールアドレスを確かめていないアカウントは、外部ツールからログインできません。アカウントの承認を先に済ませてください
  • システム連携で断られる: This endpoint is not available to client credentials(403)は、システム連携では使えない操作を呼んだときの答えです。その操作は、人のつなぎ方でつないで使ってください
  • ツールが変わったとき: AGENTIC STAR の更新でツールが変わったときは、つなぎ直してください(Claude Code は /mcp)

関連ドキュメント​