# EchoScan MCP Server

EchoScan exposes a production remote MCP server at `https://api.echoscan.org/mcp`. It uses Streamable HTTP and OAuth 2.1 Authorization Code with PKCE S256. A Secret API Key is never used as an OAuth bearer token.

## Connect from Codex

1. Open Codex Settings, choose **MCP servers**, and add `https://api.echoscan.org/mcp`.
2. Choose OAuth authentication.
3. Sign in to EchoScan, select one Workspace, review the requested capabilities, and authorize the client.
4. Return to Codex. EchoScan rechecks membership, plan entitlements, rate limits, and monthly quota on every call.

## Tools

- `echoscan_get_report`: reads the existing Lite or Pro Report contract for an Imprint. Pass `depth: lite | pro`.
- `echoscan_get_history`: reads the existing History contract; Pro entitlement is required.
- `echoscan_get_usage`: reads the current Workspace plan, entitlement summary, request usage, shared quota, and RPS limit.
- `echoscan_get_trial_status`: returns `not_applicable` for human OAuth Workspace sessions.

## OAuth scopes

- `echoscan.report.lite`
- `echoscan.report.pro`
- `echoscan.history.read`
- `echoscan.usage.read`
- `echoscan.trial.status`

Pro Report and History scopes are offered only when the selected Workspace currently has the matching entitlements. Tokens are bound to the user, Workspace, client, resource, and granted scopes. Access tokens are short-lived; refresh tokens rotate and reuse revokes the authorization relationship.

## Browser Verifier and usage boundary

The Browser Verifier still runs in a real browser origin and produces the Imprint. MCP does not generate or simulate browser fingerprints; an AI or server uses `echoscan_get_report` only after receiving that Imprint. MCP calls and authenticated HTTP API calls consume the same Workspace monthly quota and rate policy.

MCP is an additional access surface. It does not replace the OpenAPI-described HTTP API.

## Discovery and revocation

OAuth Protected Resource Metadata is published at `https://api.echoscan.org/.well-known/oauth-protected-resource/mcp`. Authorization Server Metadata is published at `https://api.echoscan.org/.well-known/oauth-authorization-server`. Compatible clients can use Client ID Metadata Documents or Dynamic Client Registration.

To remove access, revoke the EchoScan MCP authorization from the client. Workspace membership or entitlement removal also takes effect on subsequent calls.

The existing REST API, Agent Trial, and x402-compatible purchase flow remain separate contracts.