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

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

## 用意するもの

- 使う AI クライアント（Claude Code・Codex・Cursor・VS Code・Claude）
- 人がつなぐとき: Console で作ったアプリケーション（Client ID）
- システム連携でつなぐとき: Console で作ったシステム連携と、その API キー

## プラグインで入れる（おすすめ）

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

| 入っているもの                | 役割                                 |
| ---------------------- | ---------------------------------- |
| `agenticstar-connect`  | AGENTIC STAR の MCP につなぐ手順を案内する     |
| `agenticstar-projects` | プロジェクトを作る・失敗を調べて直す・確認依頼を片付ける・結果を読む |

- MCP の接続設定は入っていません。Client ID や API キーは、案内に沿って設定します
- マーケットプレイス版とは別のプラグインです。SaaS版ではこのページのプラグインを使ってください
- 今の版: `3.4.0`

[プラグインをダウンロード（agenticstar.zip）](https://developers.fd.agenticstar.tm.softbank.jp/plugins/agenticstar.zip)

**Claude Code**

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

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

**Codex**

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

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

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

**Claude**

claude.ai または Claude Desktop の **Customize > Plugins** で **Add > Upload plugin** を選び、zip をそのまま選びます。

## つなぎ方を選ぶ

| 使う人            | つなぎ方                                    | Console で用意するもの     |
| -------------- | --------------------------------------- | ------------------- |
| 人（自分のアカウントで使う） | クライアントでログインする                           | アプリケーション（Client ID） |
| 仕組み（システム連携）    | 固定の API キーを `Authorization: Bearer` に書く | システム連携の API キー      |

MCP のエンドポイントは次のとおりです。使うツールの組を `toolsets` で選びます（[ツールの組](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/mcp-ref.md#%E3%83%84%E3%83%BC%E3%83%AB%E3%81%AE%E7%B5%84toolsets)）。

```text
https://api.fd.agenticstar.tm.softbank.jp/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)・[Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)）。ほかの MCP クライアントでは、エンドポイント・Client ID・Redirect URI を、そのクライアントの文書に沿って設定してください。

## 人がつなぐ

### 1. Console でアプリケーションを作る

[Console ガイド — アプリケーションの作成手順](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#%E3%82%A2%E3%83%97%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90%E6%89%8B%E9%A0%86) に沿って作ります。

- **アプリケーションの種類**: 「モバイル / ネイティブ」を選びます（Client Secret を持たず、PKCE でログインします）
- **Redirect URI**: 使うクライアントの戻り先を登録します（下の表）。使うものを全部登録してください
- **スコープ**: `mcp:connect` と、使うツールのスコープを選びます。ツールごとのスコープは [MCP API リファレンス — 提供ツール](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/mcp-ref.md#%E6%8F%90%E4%BE%9B%E3%83%84%E3%83%BC%E3%83%AB) にあります（例: チャットの組を使うなら `chat:exec`、プロジェクトを読むなら `project:read`）

| クライアント          | 登録する Redirect URI                                             |
| --------------- | ------------------------------------------------------------- |
| Claude Code     | `http://localhost:<ポート>/callback`（`--callback-port` に指定するポート） |
| Codex           | `callback_url` に書く値（例: `http://localhost:<ポート>/callback`）     |
| Cursor（デスクトップ版） | `http://localhost:8787/callback`                              |
| VS Code         | `http://127.0.0.1/` と `https://vscode.dev/redirect`           |
| Claude          | `https://claude.ai/api/mcp/auth_callback`                     |

- 戻り先が `http://127.0.0.1`・`http://[::1]`・`http://localhost` のときは、ポートを問いません。ポートを除いて登録すると（例: `http://localhost/callback`）、クライアントがどのポートを使ってもログインできます。ポートを付けて登録したときは、そのポートだけです
- 戻り先を自分で決められるクライアント（Codex の `callback_url` など）では、`localhost` より `127.0.0.1` をおすすめします
- 前に VS Code 用に `http://127.0.0.1:33418/` を登録したクライアントは、`http://127.0.0.1/` を足してください

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

`<client_id>` には、作ったアプリケーションの Client ID を入れます。

**Claude Code**

```bash
claude mcp add --scope user --transport http \
  --client-id <client_id> --callback-port <ポート> \
  agenticstar 'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project'
```

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

**Codex**

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

```toml
[mcp_servers.agenticstar]
url = "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project"

[mcp_servers.agenticstar.oauth]
client_id = "<client_id>"
callback_port = <ポート>
callback_url = "http://localhost:<ポート>/callback"
```

`codex mcp login agenticstar` を実行すると、ブラウザでログインの画面が開きます。

**Cursor**

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

```json
{
  "mcpServers": {
    "agenticstar": {
      "url": "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project",
      "oauth": {
        "clientId": "<client_id>"
      }
    }
  }
}
```

コマンドパレットの「MCP: List Servers」からサーバーを起動すると、ブラウザでログインの画面が開きます。

- ツールをチャットから使うには、VS Code のチャット（GitHub Copilot）が使える必要があります
- チャット欄の **Session Target** は **Local**（ローカル）にしてください。ほかの動かし手（Copilot など）には、この設定が渡らず、つながりません
- 前のログインが残っているときは、VS Code のアカウントからサインアウトしてからやり直してください

**Claude**

1. カスタムコネクタを足す画面を開きます

   <!-- -->

   - Free・Pro・Max プラン: **Customize > Connectors**（カスタマイズ › コネクタ）で **+ Add**（＋ 追加）から **Add custom connector**（カスタムコネクタを追加）を選びます（Free プランはカスタムコネクタ 1 つまで）
   - Team・Enterprise プラン: Owner が **Organization settings > Connectors** で **Add** から **Custom**（**Web**）を選びます

2. 名前と、上のエンドポイントの URL（`?toolsets=chat,project` 付き）を入れて、**Continue**（続ける）を選びます

3. 次の画面の **OAuth client** が **Use your own OAuth client**（独自の OAuth クライアントを使用する）になっていることを確かめ、Client ID を入れます（Secret は空のままにします）。AGENTIC STAR では、**Authentication** と **OAuth client** は自動で選ばれます。**Add**（追加）を選びます

4. Free・Pro・Max プランでは、続けて **Connect**（連携）を選び、開いたブラウザで AGENTIC STAR にログインします。Team・Enterprise プランでは、Owner が足した後、各メンバーが **Customize > Connectors** で **Custom** の付いたコネクタを選んで **Connect** し、自分のアカウントでログインします

ツールは、使うたびに確認を求めるのが既定です（拒否・常に許可・一度だけ許可）。

Claude は、利用者のパソコンではなく Anthropic のサーバーから AGENTIC STAR につなぎます。同じコネクタを claude.ai・Claude Desktop・Cowork で使えます。

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

1. [Console ガイド — システム連携の作成手順](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#%E3%82%B7%E3%82%B9%E3%83%86%E3%83%A0%E9%80%A3%E6%90%BA%E3%81%AE%E4%BD%9C%E6%88%90%E6%89%8B%E9%A0%86) に沿って作ります。スコープは `mcp:connect` と、使う操作に合わせて `project:read`・`project:run` を選び、[プロジェクト制限](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#project-restriction) を設定します
2. システム連携の詳細の画面で API キーを発行します（[Console ガイド — API キー](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#api-key)）
3. クライアントに `Authorization: Bearer <API キー>` を設定します。トークンを取り直す必要はありません

**Claude Code**

```bash
claude mcp add --scope user --transport http agenticstar-system \
  'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project' \
  --header "Authorization: Bearer <API キー>"
```

**Codex**

API キーを環境変数 `AGENTICSTAR_API_KEY` に入れておき、`~/.codex/config.toml` に書きます。

```toml
[mcp_servers.agenticstar-system]
url = "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project"
bearer_token_env_var = "AGENTICSTAR_API_KEY"
```

**Cursor**

```json
{
  "mcpServers": {
    "agenticstar-system": {
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project",
      "headers": {
        "Authorization": "Bearer <API キー>"
      }
    }
  }
}
```

**VS Code**

```json
{
  "inputs": [
    { "type": "promptString", "id": "agenticstar-api-key", "description": "AGENTIC STAR の API キー", "password": true }
  ],
  "servers": {
    "agenticstar-system": {
      "type": "http",
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project",
      "headers": {
        "Authorization": "Bearer ${input:agenticstar-api-key}"
      }
    }
  }
}
```

チャット欄の **Session Target** は **Local**（ローカル）にしてください。`${input:…}` を使うサーバーは、ほかの動かし手（Copilot など）には渡りません。

システム連携で使えるのは、プロジェクトの組の 5 つの操作（`project_read` の `list`・`run_read` の `get`・`project_run` の `start_run`・`fire_trigger`・`cancel_run`）と、チャットの組の `list_personas` です（`list_personas` を使うときは `toolsets=chat,project`）。扱えるのは、プロジェクト制限の範囲のプロジェクトだけです。Claude では、システム連携のつなぎ方はありません。

## 安全に使う

- **書き込む操作**: プロジェクトを作る・変える・消す、確認依頼を決めるなどの操作を AI に任せるときは、クライアントの許可の仕組みで、実行の前に確かめられるようにしてください（Claude Code は、確認依頼を決める前に毎回許可を求めます。Claude は、ツールごとに許可を設定できます。ほかのクライアントは、そのクライアントの文書を確認してください）
- **読むだけで使う**: 読むだけで使うときは、スコープを `mcp:connect` と `project:read` だけにしたアプリケーションを作ってください
- **API キー**: API キーは、Client Secret と同じく秘密の値として扱ってください。チャットや文書に貼らないでください
- **資格情報が漏れたとき**: 人がつなぐときは、Console でアプリケーションを削除してください。システム連携は、API キーを削除するか、システム連携を無効化してください。反映まで最大 1 分ほどかかります（[Console ガイド — 資格情報が漏れたとき](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#if-credentials-leak)）

## つながらないとき

- **ツールの組**: `toolsets` を指定しないと、チャットの組だけになります。プロジェクトの組を使うときは `project` を指定してください
- **Redirect URI の食い違い**: ログインの画面で Redirect URI のエラーが出たときは、クライアントの戻り先と、Console に登録した Redirect URI が合っているかを確かめてください（Claude Code・Codex はポート）
- **スコープの不足**: スコープが足りないツールを呼ぶと、ツールのエラーで、要るスコープと次にやることが返ります。人のアプリケーションでは、Console でスコープを足してからログインし直してください
- **システム連携の範囲**: システム連携で扱えるのは、プロジェクト制限の範囲のプロジェクトだけです
- **システム連携で断られる**: `This endpoint is not available to client credentials`（403）は、システム連携では使えない操作を呼んだときの答えです。その操作は、人のつなぎ方でつないで使ってください
- **前段の仕組み（WAF）**: 入力の内容によっては、前段の仕組みでリクエストが止められます。このときは HTTP の `403` で、本文の JSON の `error.code` が `waf_blocked` です。参照番号があるときは `error.reference` に入ります
- **ツールが変わったとき**: AGENTIC STAR の更新でツールが変わったときは、つなぎ直してください（Claude Code は `/mcp`、Claude はコネクタのメニューからツールの一覧を更新します）

## 関連ドキュメント

- [MCP API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/mcp-ref.md) — ツール・スコープ・エラーの仕様
- [認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md) — トークンの取り方とスコープ
- [Console ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md) — アプリケーション・システム連携・API キーの作り方
- [接続方式ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md) — REST・MCP・A2A の選び方
