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-connect | AGENTIC STAR の MCP につなぐ手順を案内する |
agenticstar-projects | 登録 Agent でプロジェクトを作る・失敗を調べる・確認依頼を片付ける・結果を読む |
- MCP の接続設定は入っていません。クライアント ID などは、案内に沿って設定します
- SaaS版とは別のプラグインです。マーケットプレイス版ではこのページのプラグインを使ってください
- 今の版:
3.4.0
プラグインをダウンロード(agenticstar-mp.zip)
- Claude Code
- Codex
zip を展開したフォルダで、次を実行します(Claude Code 2.1.292 以降)。
claude plugin install agenticstar-mp --marketplace ./agenticstar-mp
zip を展開したフォルダで、次を実行します。
codex plugin marketplace add ./agenticstar-mp
codex plugin add agenticstar-mp@agenticstar-mp
プラグインの手順書は、Codex がシェルで読みます。シェルを使える状態で使ってください。
つなぎ方を選ぶ
| 使う人 | つなぎ方 | 用意するもの |
|---|---|---|
| 人(自分のアカウントで使う) | クライアントでログインする | 外部ツールのクライアント(クライアント 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
証明書の確かめを切って起動します。
NODE_TLS_REJECT_UNAUTHORIZED=0 claude
確かめを切ると、通信が盗み見られたり書き換えられたりしても気付けません。試す間だけ、その起動の中だけで使ってください。
Codex
入口の証明書を取り出して、Codex に信じさせます。
-
入口の証明書をファイルに保存します(
<your-domain>は外部 API の入口の住所)curlopenssl s_client -connect <your-domain>:443 -showcerts < /dev/null | openssl x509 > agentic-star.crt -
環境変数
CODEX_CA_CERTIFICATEに、保存したファイルのパスを入れてから Codex を起動します(codex mcp loginの前に)curlexport 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 を入れます。
- Claude Code
- Codex
- Cursor
- VS Code
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 を実行すると、ブラウザでログインの画面が開きます。
~/.codex/config.toml に書きます。
[mcp_servers.agenticstar]
url = "https://<your-domain>/api/v1/mcp?toolsets=chat,project"
scopes = ["openid"]
[mcp_servers.agenticstar.oauth]
client_id = "<client_id>"
callback_port = <ポート>
callback_url = "http://localhost:<ポート>/callback"
codex mcp login agenticstar を実行すると、ブラウザでログインの画面が開きます。scopes = ["openid"] は省かないでください。Codex が求めるスコープを openid だけにする設定で、AGENTIC STAR が案内するスコープは openid だけなので、この設定のままでログインできます。
プロジェクトの .cursor/mcp.json(または ~/.cursor/mcp.json)に書きます。
{
"mcpServers": {
"agenticstar": {
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"auth": {
"CLIENT_ID": "<client_id>"
}
}
}
}
サイドバーの Customize の MCP の一覧で agenticstar を有効にし、ログインを求められたら進めます。プロジェクトの .cursor/mcp.json に書いたサーバーは、そのプロジェクトの中で始めたチャットで使えます。
ワークスペースの .vscode/mcp.json に書きます。
{
"servers": {
"agenticstar": {
"type": "http",
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"oauth": {
"clientId": "<client_id>"
}
}
}
}
コマンドパレットの「MCP: List Servers」からサーバーを起動すると、ブラウザでログインの画面が開きます。
- ツールをチャットから使うには、VS Code のチャット(GitHub Copilot)が使える必要があります
- チャット欄の Session Target は Local(ローカル)にしてください。ほかの動かし手(Copilot など)には、この設定が渡らず、つながりません
システム連携でつなぐ
- API 利用準備ガイド — システム連携の作成手順 に沿って、管理コンソールでサービスアカウントを作ります
- 認証ガイド — Client Credentials フロー で、
https://<auth-domain>/api/v1/oauth/tokenからアクセストークンを取ります - クライアントに
Authorization: Bearer <access_token>を設定します。トークンの有効期限が切れたら、同じ手順で取り直して設定し直します(トークンの再取得)
- Claude Code
- Codex
- Cursor
- VS Code
claude mcp add --scope user --transport http agenticstar-system \
'https://<your-domain>/api/v1/mcp?toolsets=chat,project' \
--header "Authorization: Bearer <access_token>"
トークンを環境変数 AGENTICSTAR_TOKEN に入れておき、~/.codex/config.toml に書きます。
[mcp_servers.agenticstar-system]
url = "https://<your-domain>/api/v1/mcp?toolsets=chat,project"
bearer_token_env_var = "AGENTICSTAR_TOKEN"
{
"mcpServers": {
"agenticstar-system": {
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"headers": {
"Authorization": "Bearer <access_token>"
}
}
}
}
{
"inputs": [
{ "type": "promptString", "id": "agenticstar-token", "description": "AGENTIC STAR のアクセストークン", "password": true }
],
"servers": {
"agenticstar-system": {
"type": "http",
"url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
"headers": {
"Authorization": "Bearer ${input:agenticstar-token}"
}
}
}
}
チャット欄の Session Target は Local(ローカル)にしてください。${input:…} を使うサーバーは、ほかの動かし手(Copilot など)には渡りません。
システム連携で使えるのは、チャットの組のツール、プロジェクトの組の 9 つの操作(project_read の list・run_read の get・list_artifacts・get_artifact_content・execution_read の get(状態の項目だけ)・project_run の start_run・fire_trigger・cancel_run・cancel_execution)、公開したツールの組のツールです。システム連携のトークンでは、この環境にあるすべてのプロジェクトを扱えます。
安全に使う
- 書き込む操作: プロジェクトを作る・変える・消す、確認依頼を決めるなどの操作を AI に任せるときは、クライアントの許可の仕組みで、実行の前に確かめられるようにしてください(Claude Code は、確認依頼を決める前に毎回許可を求めます。ほかのクライアントは、そのクライアントの文書を確認してください)
- トークンとシークレット: アクセストークンとクライアントシークレットは、秘密の値として扱ってください。チャットや文書に貼らないでください
- 外部ツールを止めるとき: ログインした外部ツールは、メイン画面からログアウトしても止まりません。止め方は API 利用準備ガイド — 外部ツールを止める を参照してください
- 資格情報が漏れたとき: 管理コンソールでサービスアカウントを無効化するか、クライアントシークレットを作り直してください(API 利用準備ガイド — 資格情報が漏れたとき)
つながらないとき
- 呼び出しが 401(
WWW-Authenticateヘッダーにresource_metadataが無い)か 404 になる: MCP の受け口か、外部ツールでのログインの入口が、この環境で開いていません。管理者に確かめてください - 証明書のエラー: ドメインを設定していない環境で確かめるとき を参照してください
- ツールの組:
toolsetsを指定しないと、チャットの組だけになります。プロジェクトの組を使うときはproject、公開したワークフローを呼ぶときはpublishedを指定してください - ログインが断られる: 承認待ちのアカウントと、メールアドレスを確かめていないアカウントは、外部ツールからログインできません。アカウントの承認を先に済ませてください
- システム連携で断られる:
This endpoint is not available to client credentials(403)は、システム連携では使えない操作を呼んだときの答えです。その操作は、人のつなぎ方でつないで使ってください - ツールが変わったとき: AGENTIC STAR の更新でツールが変わったときは、つなぎ直してください(Claude Code は
/mcp)
関連ドキュメント
- MCP API リファレンス — ツール・エラーの仕様
- 認証ガイド — トークンの取り方
- API 利用準備ガイド — 外部ツールのクライアントとサービスアカウントの作り方
- 接続方式ガイド — REST・MCP・A2A の選び方