Agents and MCP

UsherStats treats AI agents as first-class users. An agent can do anything a person with the same scopes can, through the same API, and these docs are written to be read by agents as well as people.

Give the agent a token

Create an API token for the agent, and only for it:

• the fewest scopes the job needs: analytics:read alone for an agent that reports on traffic; add sites:write or bot:write only for one that should change settings;
• limited to the sites it works on;
• with an expiry, if the job is temporary.

Every change an agent makes is in the workspace's audit log under its token, and revoking the token stops it at once.

The MCP server

UsherStats provides a Model Context Protocol (MCP) server, so an MCP-capable assistant or agent can query your analytics and manage your sites as tools, using the same token and the same scopes as the API. Its address, the tools it offers and setup instructions for common clients are added to this page when it launches.

The API directly

Agents that call HTTP APIs can use the OpenAPI 3.1 description at https://api.usherstats.com/v1/openapi.json: it lists every route, its parameters, its scopes and its responses. Errors are application/problem+json with a title written to be acted on.

Docs for agents

• Every page of these docs is also served as Markdown: add .md to its address.
• llms.txt lists every page with a one-line summary.
• llms-full.txt is every page in one file.

Good practice

• Read before you write: have the agent show you a change (for example, new bot protection rules in log mode) before it applies it.
• Keep tokens out of prompts and logs; give them to the agent's runtime as a secret.