# 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.

Command-line setup:

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

## Connect from Claude Code

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

## Connect from VS Code

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

## Connect from another MCP client

Choose Streamable HTTP, use `https://api.echoscan.org/mcp`, and select OAuth 2.1 authentication. The client follows the published OAuth metadata to open browser authorization.

## 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_integration_plan`: returns the non-sensitive Agent Installer plan and local CLI command.
- `echoscan_installation_status`: reads persistent Installation state without returning credentials.
- `echoscan_installation_verify`: checks real Browser Environment and Server Credential connection evidence.

## OAuth scopes

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

For a supported Next.js App Router TypeScript pnpm project, call `echoscan_integration_plan`, then run `npx @echoscan/cli init --agent --json` locally. OAuth tokens and the one-time API key travel only through the CLI process; MCP tool results never contain them.

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`. Client ID Metadata Documents (CIMD) are the canonical integration path: the HTTPS `client_id` is the metadata document URL. EchoScan also publishes a controlled Dynamic Client Registration (DCR) compatibility endpoint at `https://api.echoscan.org/oauth/register` for clients, including current Codex versions, that do not yet support CIMD. A DCR response is temporary and creates no durable OAuth client until the user explicitly allows access on the consent page.

Before authorization, the consent page shows the client-declared name and whether that identity is verified: a CIMD client is verified by the hostname of its metadata document, while a DCR compatibility client is marked as unverified because the name is self-declared. The page also states where the result goes; a loopback redirect is described as an application on the current device rather than as an ephemeral port. The opaque client ID, the exact redirect URI, the protocol, and the resource remain available under technical details. EchoScan's long-lived QA CIMD document is `https://echoscan.org/.well-known/oauth-client/mcp-qa.json` and is intended for controlled MCP Inspector acceptance testing.

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.