# Authenticated MCP access

The MCP endpoint is `https://purestats.io/mcp`, using Streamable HTTP and OAuth.
Check `/llms.txt` for this deployment's enabled status. An enabled endpoint
requires OAuth for every MCP request, including protocol initialization and
tool-schema discovery. Public documentation and OAuth metadata remain available
without a token. Every tool checks its scopes and current site access before
reading data or performing an action. Responses are not cached and do not
issue session cookies.

## Discovery

Read `https://purestats.io/.well-known/oauth-protected-resource/mcp` and
`https://purestats.io/.well-known/oauth-authorization-server`. Requests without a
valid token, including the first `initialize` request, return HTTP 401 with
`WWW-Authenticate: Bearer` and a `resource_metadata` URL. Connect with OAuth before
initializing the protocol or listing tools. Authenticated tool schemas declare
their required OAuth scopes.
Use the published issuer and endpoints, not dashboard URLs or a guessed callback.
Tokens must be bound to `resource=https://purestats.io/mcp`; a management API
token does not authorize MCP access.

## Client registration and consent

There is no open dynamic client registration. Clients must be explicitly
registered. The Claude Code native client uses ID
`3e479817-9c7d-4e2b-b722-3263f8969001` and exactly
`http://localhost:18437/callback` or `http://127.0.0.1:18437/callback`.
ChatGPT can identify its preregistered application using the official
`https://chatgpt.com/oauth/client.json` metadata document. PureStats fetches and
validates only that exact HTTPS document, including its published stable callback
and public-client token method. Arbitrary metadata URLs and callbacks are rejected;
this is not open dynamic registration. A manually configured ChatGPT client can
still use the exact callback copied from its publisher portal. Package upload alone
is not a successful OAuth connection or platform approval.

For hosts that use a registration endpoint instead of the metadata-document
identity, discovery also advertises `https://purestats.io/oauth/register`.
This compatibility endpoint only returns the existing ChatGPT application for
the exact stable callback validated against ChatGPT's official metadata. It
accepts public authorization-code clients with PKCE, not arbitrary applications,
redirects or client-credentials grants. Repeated registration keeps the same
client ID and does not create an account, issue a token, change an existing grant
or confer access to any site. Browser consent is still required.

Use authorization code with PKCE S256. A person signs in through PureStats and
explicitly selects sites and scopes. Start with `account:read`, `sites:read` and
`analytics:read`. Account owners approve additional capabilities separately.
Access tokens last 15 minutes; rotating refresh tokens last 30 days. Never put
tokens, passwords or client secrets in a plugin package, tracker or conversation.

## Tools and safety

Tools reuse the [public canonical operation catalog](/openapi.json). The MCP
tool list is authenticated and limited to the granted scopes. Follow
the actual schemas. Scope and current
site membership are checked for every call. Revoked access stops working
immediately; an administrator's agent has no global admin bypass.

Deletion, ownership transfer and security changes still need payload-bound human
approval on PureStats. A chat message cannot replace that approval. Review
recordings must use a dedicated account with synthetic data and must not expose
credentials or other customers' sites. ChatGPT acceptance, its real recording
and official directory listings remain pending; a server canary proves only
the server-side protocol, not a ChatGPT installation.

## Troubleshooting

- A disabled endpoint is not an authentication failure; check the deployment status first.
- HTTP 401 requires valid OAuth access for the MCP resource. Invalid or revoked
  bearer tokens cannot initialize the protocol or discover tools.
- An initial request without a bearer token receives a bare OAuth challenge, not
  `invalid_token`. That error is reserved for a supplied token that cannot be
  accepted. If Connect fails immediately while the portal still shows `No Auth`,
  check OAuth discovery and client registration before rotating credentials.
  A working connection must open browser consent and obtain a token first.
- Reconnect a stale publisher connection after discovery changes. The server advertises
  both the known ChatGPT registration endpoint and client metadata support, with
  the initial read-only scopes in its challenge. A host that requires registration
  must complete that step before opening the account-consent page.
- `This MCP server exposes OAuth-only actions. Update the draft's auth_types to
  include OAUTH` means the publisher draft still permits only `No Auth`. Set the
  MCP connection's authentication through the package before scanning. The supported
  field is `mcpServers.purestats.extensions.com.openai.auth` in `mcp.json`, with
  `type: oauth`, `client.mode: cimd` and the initial read-only scopes. PureStats
  review package 0.1.3 includes this setting; upload it as a new version of the
  existing draft, select that version, then reconnect. The portal's connection
  panel displays saved settings and may not offer an editable authentication
  selector. A successful domain verification does not configure OAuth. No
  `auth_types` ZIP field, token header or anonymous tool access is needed.
  See the [OpenAI package reference](https://developers.openai.com/plugins/build/plugins).
- An unknown client or callback requires operator registration, not wildcard matching.
- HTTP 403 can indicate an unapproved origin, missing scope or lost site membership.
- A missing tool can be intentional for the current read-only grant.

Use the [REST quickstart](/docs/agents/quickstart.md) for autonomous machine
registration and domain verification. These are separate flows from plugin OAuth.
