# AI クライアント接続ガイド（MCP）

MCP 対応の AI クライアントから、AGENTIC STAR の MCP につなぐ手順です。チャットの組のツールでは Agent に仕事を頼み、プロジェクトの組のツールでは登録 Agent でプロジェクトを作る・動かす・確認依頼を片付けるなどができます。ツールの詳しい仕様は [MCP API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/mcp-ref.md) を参照してください。

> **始める前に**
>
> MCP は、管理者が MCP の受け口を開けた環境でだけ使えます。人が自分のアカウントでつなぐには、外部ツールでのログインの入口も開いている必要があります（[API 利用準備ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md)）。

## 用意するもの

- 使う 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）](https://developers.fd.agenticstar.tm.softbank.jp/plugins/agenticstar-mp.zip)

**Claude Code**

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

```bash
claude plugin install agenticstar-mp --marketplace ./agenticstar-mp
```

**Codex**

zip を展開したフォルダで、次を実行します。

```bash
codex plugin marketplace add ./agenticstar-mp
codex plugin add agenticstar-mp@agenticstar-mp
```

プラグインの手順書は、Codex がシェルで読みます。シェルを使える状態で使ってください。

## つなぎ方を選ぶ

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

MCP のエンドポイントは次のとおりです。使うツールの組を `toolsets` で選びます（[ツールの組](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/mcp-ref.md#%E3%83%84%E3%83%BC%E3%83%AB%E3%81%AE%E7%B5%84toolsets)）。公開したワークフローも呼ぶときは `published` を足します。

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

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

> **設定の例について**
>
> このページの設定は、参考のための例です。設定の方法は、クライアントの版によって変わることがあります。最新の方法は、各クライアントの文書を確認してください（[Claude Code](https://code.claude.com/docs/en/mcp)・[Codex](https://learn.chatgpt.com/docs/extend/mcp)・[Cursor](https://cursor.com/docs/mcp)・[VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)）。ほかの MCP クライアントでは、エンドポイントとクライアント ID を、そのクライアントの文書に沿って設定してください。

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

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

### Claude Code

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

```bash
NODE_TLS_REJECT_UNAUTHORIZED=0 claude
```

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

### Codex

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

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

   ```bash
   openssl s_client -connect <your-domain>:443 -showcerts < /dev/null | openssl x509 > agentic-star.crt
   ```

2. 環境変数 `CODEX_CA_CERTIFICATE` に、保存したファイルのパスを入れてから Codex を起動します（`codex mcp login` の前に）

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

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

### Cursor・VS Code

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

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

必ずドメインと証明書を設定してください。設定すれば、どちらの設定も要りません（[ドメイン設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/domain-guide.md)）。

## 人がつなぐ

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

管理者が、[API 利用準備ガイド — 外部ツールのクライアントの作成手順](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md#external-tool-client) に沿って、認証サーバーのコンソールでクライアントを作ります。戻り先には `http://localhost/callback` と `http://127.0.0.1/callback` を登録します。VS Code を使うときは `http://127.0.0.1/` も登録します。ポートは問われないので、下のクライアントで指定するポートは、空いているものを自由に選べます。

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

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

**Claude Code**

```bash
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**

`~/.codex/config.toml` に書きます。

```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**

プロジェクトの `.cursor/mcp.json`（または `~/.cursor/mcp.json`）に書きます。

```json
{
  "mcpServers": {
    "agenticstar": {
      "url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
      "auth": {
        "CLIENT_ID": "<client_id>"
      }
    }
  }
}
```

サイドバーの **Customize** の MCP の一覧で `agenticstar` を有効にし、ログインを求められたら進めます。プロジェクトの `.cursor/mcp.json` に書いたサーバーは、そのプロジェクトの中で始めたチャットで使えます。

**VS Code**

ワークスペースの `.vscode/mcp.json` に書きます。

```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 など）には、この設定が渡らず、つながりません

## システム連携でつなぐ

1. [API 利用準備ガイド — システム連携の作成手順](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md#service-account) に沿って、管理コンソールでサービスアカウントを作ります
2. [認証ガイド — Client Credentials フロー](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md#%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%81%AE%E5%8F%96%E5%BE%97) で、`https://<auth-domain>/api/v1/oauth/token` からアクセストークンを取ります
3. クライアントに `Authorization: Bearer <access_token>` を設定します。トークンの有効期限が切れたら、同じ手順で取り直して設定し直します（[トークンの再取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md#%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%81%AE%E5%86%8D%E5%8F%96%E5%BE%97)）

**Claude Code**

```bash
claude mcp add --scope user --transport http agenticstar-system \
  'https://<your-domain>/api/v1/mcp?toolsets=chat,project' \
  --header "Authorization: Bearer <access_token>"
```

**Codex**

トークンを環境変数 `AGENTICSTAR_TOKEN` に入れておき、`~/.codex/config.toml` に書きます。

```toml
[mcp_servers.agenticstar-system]
url = "https://<your-domain>/api/v1/mcp?toolsets=chat,project"
bearer_token_env_var = "AGENTICSTAR_TOKEN"
```

**Cursor**

```json
{
  "mcpServers": {
    "agenticstar-system": {
      "url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

**VS Code**

```json
{
  "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 利用準備ガイド — 外部ツールを止める](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md#stop-external-tool) を参照してください
- **資格情報が漏れたとき**: 管理コンソールでサービスアカウントを無効化するか、クライアントシークレットを作り直してください（[API 利用準備ガイド — 資格情報が漏れたとき](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md#if-credentials-leak)）

## つながらないとき

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

## 関連ドキュメント

- [MCP API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/mcp-ref.md) — ツール・エラーの仕様
- [認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md) — トークンの取り方
- [API 利用準備ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md) — 外部ツールのクライアントとサービスアカウントの作り方
- [接続方式ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/connection-guide.md) — REST・MCP・A2A の選び方
