# EchoScan MCP Server

EchoScan の正式なリモート MCP Server は `https://api.echoscan.org/mcp` です。Streamable HTTP と OAuth 2.1 Authorization Code + PKCE S256 を使用します。Secret API Key を OAuth Bearer Token として使用することはありません。

## Codex から接続

1. Codex の設定で **MCP servers** を開き、`https://api.echoscan.org/mcp` を追加します。
2. OAuth 認証を選択します。
3. EchoScan にログインし、Workspace を1つ選択して、要求された機能を確認してから認可します。
4. Codex に戻ります。EchoScan は呼び出しごとに、メンバーシップ、プラン権限、レート制限、月間クォータを再確認します。

コマンドライン設定：

```bash
codex mcp add echoscan --url https://api.echoscan.org/mcp
```

## Claude Code から接続

```bash
claude mcp add --transport http echoscan https://api.echoscan.org/mcp
```

## VS Code から接続

```json
{
  "servers": {
    "echoscan": {
      "type": "http",
      "url": "https://api.echoscan.org/mcp"
    }
  }
}
```

## その他の MCP Client から接続

Streamable HTTP を選択し、URL に `https://api.echoscan.org/mcp`、認証に OAuth 2.1 を指定します。クライアントは公開 OAuth Metadata に従ってブラウザー認可を開きます。

## Tools

- `echoscan_get_report`: Imprint の既存 Lite または Pro Report 契約を読み取ります。`depth: lite | pro` を指定します。
- `echoscan_get_history`: 既存の History 契約を読み取ります。Pro 権限が必要です。
- `echoscan_get_usage`: 現在の Workspace プラン、権限概要、使用量、共有クォータ、RPS 制限を読み取ります。
- `echoscan_integration_plan`: 機密情報を含まない Agent Installer プランとローカル CLI コマンドを返します。
- `echoscan_installation_status`: 認証情報を返さず、永続 Installation 状態を取得します。
- `echoscan_installation_verify`: 実際の接続証拠から Browser Environment と Server Credential を検証します。

## OAuth scopes

- `echoscan.report.lite`
- `echoscan.report.pro`
- `echoscan.history.read`
- `echoscan.usage.read`
- `echoscan.integration.read`
- `echoscan.integration.write`

Pro Report と History の scope は、選択した Workspace に対応する権限が現在ある場合のみ表示されます。Token はユーザー、Workspace、クライアント、リソース、許可 scope に結び付けられます。Access Token は短期間で失効し、Refresh Token は使用ごとにローテーションされ、再利用を検出すると認可関係全体を失効させます。

## Browser Verifier と使用量の境界

Browser Verifier は引き続き実際の Browser Origin で実行され、Imprint を生成します。MCP はブラウザフィンガープリントを生成または模倣しません。AI またはサーバーは、その Imprint を受け取った後にだけ `echoscan_get_report` でレポートを参照します。MCP 呼び出しと認証済み HTTP API 呼び出しは、同じ Workspace の月間クォータとレートポリシーを消費します。

MCP は追加のアクセスサーフェスであり、OpenAPI で記述された HTTP API を置き換えません。

## 検出と取り消し

OAuth Protected Resource Metadata は `https://api.echoscan.org/.well-known/oauth-protected-resource/mcp`、Authorization Server Metadata は `https://api.echoscan.org/.well-known/oauth-authorization-server` に公開されます。Client ID Metadata Documents（CIMD）が標準の統合経路であり、HTTPS の `client_id` がメタデータ文書 URL になります。現在の Codex を含む CIMD 未対応クライアント向けに、EchoScan は `https://api.echoscan.org/oauth/register` で制御された Dynamic Client Registration（DCR）互換エンドポイントも公開します。DCR が返す ID は一時的であり、ユーザーが Consent 画面で明示的に許可するまで永続 OAuth クライアントは作成されません。

認可前に、Consent 画面にはクライアントが申告した名前、CIMD ID の URL／ホスト名または DCR 互換 ID、正確なリダイレクト先が表示されます。Loopback リダイレクトはローカルアプリケーションのコールバックとして明示され、認可結果が現在の端末上のアプリへ戻ることを確認できます。EchoScan の長期 QA 用 CIMD 文書は `https://echoscan.org/.well-known/oauth-client/mcp-qa.json` で、制御された MCP Inspector 受け入れテスト専用です。

クライアントから EchoScan MCP 認可を取り消せます。Workspace のメンバーシップまたは権限が削除された場合も、以後の呼び出しに反映されます。

既存の REST API、Agent Trial、x402-compatible 購入フローは、それぞれ独立した契約のままです。