---
title: Agents and MCP
description: Give an AI agent access to UsherStats through the API, the OpenAPI description, the MCP server and these docs as Markdown.
nav: Agents & MCP
---
# 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](api-and-tokens.md#tokens) 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](https://docs.usherstats.com/llms.txt) lists every page with a one-line summary.
- [llms-full.txt](https://docs.usherstats.com/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.