> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# Addie を AI クライアントに接続する

> AAO MCP サーバーを Claude Desktop、Claude Code、ChatGPT、その他の MCP 互換クライアントに追加する — よくある「reconnection failed」エラーのトラブルシューティング付き。

# Addie を AI クライアントに接続する

Addie は `https://agenticadvertising.org/mcp` のホストされた MCP エンドポイントで動作します。streamable HTTP を話すほとんどの MCP クライアントが接続できます — Claude Desktop、Claude Code、ChatGPT、MCP SDK 上に構築されたカスタムクライアント。このページは各インストールステップと、最も一般的な失敗モードから回復する方法をカバーします。

Addie が *何ができる* かについてのエンドユーザーヘルプは、[メンバー向け AAO](/docs/aao/users) と [Addie ツールリファレンス](/docs/aao/addie-tools) を参照してください。

## 認証の概要

エンドポイントはすべてのリクエストで認証を要求します。2 つの認証情報タイプを受け入れます:

* **OAuth 2.1 ユーザー JWT** — 人間駆動クライアント（Claude Desktop、Claude Code、ChatGPT、Cursor）用。AAO メールでサインイン。クライアントが OAuth フローを処理します。
* **WorkOS 組織 API キー** — サーバー間呼び出し元用。[agenticadvertising.org/dashboard/api-keys](https://agenticadvertising.org/dashboard/api-keys) で生成。`Authorization: Bearer <key>` として送信し OAuth を完全にスキップ。

特定の接続では一方 *または* もう一方を使ってください — 両方は決してだめ。静的な `Authorization` ヘッダーが存在するとき、サーバーはリクエストを認証済みとして扱い、OAuth フローは決して開始しません。ヘッダーがあるのにクライアントがまだブラウザをポップする場合、それを剥がすか上書きしています — `claude mcp get addie`（Claude Code）またはクライアントの同等物で検証してください。

基盤となる OAuth 表面（authorization server メタデータ、動的クライアント登録、スコープ）については、このページ下部の [Reference URLs](#reference-urls) を参照してください。

## Claude Desktop

Claude Desktop の組み込み **Connectors** UI が最もスムーズなパスです。Anthropic が OAuth プロキシをホストするため、トークンを自分で管理しません。カスタムコネクターには有料 Claude プラン（Pro、Max、Team、Enterprise）が必要です。

1. Claude Desktop → Settings → Connectors を開く。
2. **Add custom connector**（または **Connect** → custom）をクリック。
3. ダイアログで Name = `Addie`、Remote MCP server URL = `https://agenticadvertising.org/mcp` を設定し、**Add** をクリック。
4. ブラウザが開いたら AAO メールでサインイン。
5. Claude Desktop が Addie を接続済みとして表示。ツールはチャットツールピッカーに現れます。

## ChatGPT

ChatGPT は **Connectors** 機能経由でリモート MCP をサポートします。カスタム MCP サーバーには有料プラン（Pro、Business、Enterprise）が必要です — Plus と Free はこのオプションを見られません。

1. ChatGPT → Settings → Connectors → Advanced → Developer mode を有効化。
2. **Create**（または **Add MCP server**）をクリックし、タイプ **MCP** を選択。
3. URL: `https://agenticadvertising.org/mcp`、Authentication: **OAuth**。
4. ブラウザでサインインを完了。

ChatGPT のコネクター UI はしばしば変わります。ラベルが正確に一致しない場合、設定で "remote MCP server" または "custom connector" を探してください。

## Claude Code

Claude Code（CLI）には [既知のバグ](https://github.com/anthropics/claude-code/issues/10250) があり、OAuth は完了するが認証後の再接続が失敗し、サーバーが `failed` とマークされます。これは Addie だけでなく、streamable-HTTP + OAuth を使うすべてのリモート MCP に影響します。Anthropic が修正を出荷するまで、下の 2 つのパスのいずれかを使ってください。

### 推奨: `mcp-remote` 経由の stdio シム

`mcp-remote` は、ローカル stdio MCP サーバーとして動作し、OAuth を自身で処理し、呼び出しをリモートエンドポイントに転送する小さな npm プロキシです。Claude Code の壊れた再接続パスを完全に回避します。Node 18 以降が必要です。

```bash theme={null}
claude mcp add addie -- npx -y mcp-remote@latest https://agenticadvertising.org/mcp
```

次に Claude Code 内で `/mcp` を実行し、ブラウザでサインインを完了します。`/mcp` は `addie  ✓ connected` を表示し、Addie のツールが即座に利用可能になります。再起動不要。

### 代替: ネイティブ HTTP トランスポート

ネイティブトランスポートを使いたい場合:

```bash theme={null}
claude mcp add --transport http addie https://agenticadvertising.org/mcp
```

`/mcp` を実行し、サインインを完了します。*"Authentication successful, but server reconnection failed"* が見えたら、Claude Code を完全に終了し（macOS では ⌘Q、ウィンドウを閉じるだけでなく）再起動してください。ときどき単一の再起動が保存されたトークンを拾います。しばしば拾いません。1 回の再起動で回復しない場合、上の `mcp-remote` パスにフォールバックしてください。

### OAuth の代わりに API キーを使う

WorkOS 組織 API キーを持っている場合、OAuth が決して実行されないよう静的 `Authorization` ヘッダーでサーバーを登録します:

```bash theme={null}
claude mcp add --transport http addie https://agenticadvertising.org/mcp \
  --header "Authorization: Bearer sk_your_key_here"
```

`claude mcp add` は他のエントリーを乱すことなく安全に `~/.claude.json` に書き込みます。そのファイルを手動編集することは動作しますが他のサーバーを壊しうる — 既に何があるか知っている場合のみ行ってください。同等の JSON 形状は:

```json theme={null}
{
  "mcpServers": {
    "addie": {
      "type": "http",
      "url": "https://agenticadvertising.org/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_key_here"
      }
    }
  }
}
```

これを OAuth フローと組み合わせないでください — 一方を選んでください。ヘッダーが存在するのに Claude Code が OAuth をトリガーする場合、キーが無効か期限切れです。[agenticadvertising.org/dashboard/api-keys](https://agenticadvertising.org/dashboard/api-keys) で新しいものを生成してください。

## その他の MCP クライアント

streamable HTTP + OAuth 2.1 を話す任意の MCP クライアントが接続できます。汎用設定:

```json theme={null}
{
  "type": "http",
  "url": "https://agenticadvertising.org/mcp"
}
```

ディスカバリーは標準パターンに従います: 最初のリクエストでの 401 は `WWW-Authenticate: Bearer resource_metadata=...` を含み、クライアントを `/.well-known/oauth-protected-resource/mcp` に向け、それが authorization server をリストします。

## トラブルシューティング

### "Authentication successful, but server reconnection failed"

これは Claude Code バグ [#10250](https://github.com/anthropics/claude-code/issues/10250) です。OAuth フローは動作した — トークンは `~/.claude/.credentials.json` に保存されている — が、クライアントがそれらで再接続に失敗しました。完全な再起動がときどき回復します。信頼できる回避策は上の `mcp-remote` インストールパスです。

これは Addie 固有ではありません: 同じエラーは Notion、Supabase、Slack、New Relic、OAuth を使う他のリモート MCP サーバーに影響します。

### OAuth 完了後に 401 が返る

クライアントが有効なトークンを持つと言うが `/mcp` へのすべてのリクエストが 401 を返す場合:

* トークンが新しいことを確認。WorkOS アクセストークンは短命です。リフレッシュトークンはより長く続きます。ほとんどのクライアントは自動リフレッシュします。一部はしません。再認証を強制してください。
* 認証情報を二重送信していないことを確認。設定に `Authorization` ヘッダー *と* OAuth フローの両方がある場合、一方が他方と衝突します。
* トークンを手動でテスト:
  ```bash theme={null}
  curl -i -X POST https://agenticadvertising.org/mcp \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"diag","version":"0.0.1"}}}'
  ```
  ここでの 401 はトークンがサーバーで拒否されたことを意味します。200 はクライアントが認証を誤処理していることを意味します。

### 再認証を強制する

保存されたトークンが古くなりクライアントが再プロンプトしないとき:

* **Claude Code:** `rm ~/.claude/.credentials.json` してから `/mcp` を実行。（これは *すべての* MCP サーバーの OAuth 状態をクリアします。複数ある場合はまずバックアップしてください。）
* **Claude Desktop:** Addie コネクターを削除して再追加。
* **ChatGPT:** 設定でコネクターを切断して再追加。

### "`~/.claude/settings.json` に Addie を設定したがロードされない"

Claude Code は MCP サーバーを `~/.claude.json`（グローバル設定）または `.mcp.json`（プロジェクトスコープ）から読みます — `settings.json` からではありません。`settings.json` は権限、フック、環境変数のみを保持します。手動編集ではなく `claude mcp add` を使ってください。

### Claude Code ログの場所

macOS: `tail -f ~/Library/Logs/Claude/mcp*.log`。tailing しながらクライアントを実行し失敗するフローをトリガーしてください — 実際のエラー（トークン拒否、トランスポート不一致、ネットワーク失敗）がそこに現れます。共有前にトークンを編集除去してください。

## Reference URLs

* **MCP エンドポイント:** `https://agenticadvertising.org/mcp`
* **Authorization server メタデータ**（RFC 8414）: `https://agenticadvertising.org/.well-known/oauth-authorization-server`
* **Protected resource メタデータ**（RFC 9728）: `https://agenticadvertising.org/.well-known/oauth-protected-resource/mcp`
* **動的クライアント登録**（RFC 7591）: `POST /register`
* **API キーダッシュボード:** [agenticadvertising.org/dashboard/api-keys](https://agenticadvertising.org/dashboard/api-keys)
* **Issue トラッカー:** [github.com/adcontextprotocol/adcp/issues](https://github.com/adcontextprotocol/adcp/issues)