MCP overview
Archive runs a Model Context Protocol server so AI agents can work with your data directly: searching content, reading creator profiles, and managing saved views, without a custom GraphQL client.
The MCP server exposes the same product surface as /api/v2. Every tool wraps exactly one public
GraphQL root field and executes it directly, with the same resolvers, the same validation, the same
workspace scoping, and the same weighted rate-limit charge. There is no second data path and no
second permission model.
POST https://app.archive.com/api/v2/mcpThe transport is Streamable HTTP carrying JSON-RPC 2.0 request bodies. The endpoint is stateless: it issues no session ID, so every request must carry its own credentials.
The tool surface
There are 42 read tools and 50 write tools. The mapping between tools
and GraphQL is one-to-one in both directions: every public query and mutation has exactly one tool,
and every tool points at exactly one public field. Anything you can do on /api/v2, you can do
over MCP, and each operation’s reference page links to the tool that wraps it.
Tool names follow the GraphQL field in camelCase, except where a different name is clearer for
agents: items is exposed as searchItems and creators as searchCreators. Everything else is
get* for a read and the mutation’s own name for a write.
- Read tools — the 42 tools that only fetch data.
- Write tools — the 50 tools that change something.
- Agent conventions — the rules that apply across every tool.
Campaign provisioning is available without an alpha header. Use getCampaign to read a campaign,
createCampaign to create one with your external key, and updateCampaign to rename it, change its
end date or update its creators and posts. Campaign writes require the normal write permission.
Creator additions run asynchronously, and valid update entries can apply alongside userErrors;
inspect returned state and operation progress before retrying uncertain work.
Authentication
The endpoint accepts two credential types, tried in this order:
| Credential | How you get it | Write access |
|---|---|---|
| Bearer token | The same API token you use for /api/v2, created in the Integration tab | Yes — parity with /api/v2, where any valid token can call every public mutation |
| OAuth 2.1 | Your MCP client registers with Archive; the person authorizes it in-app | Only if they granted the optional write scope at consent time |
Archive is its own authorization server. Tokens are opaque, Archive-issued, and validated in process; there is no JWT to decode and no introspection endpoint to call. The server publishes RFC 9728 protected-resource metadata and RFC 8414 authorization-server metadata, and supports RFC 7591 Dynamic Client Registration, so a compliant client can discover and register on its own. See Connect a client.
An unauthenticated initialize, tools/list, or tools/call returns HTTP 401 with a
WWW-Authenticate challenge — the signal MCP clients use to begin the OAuth flow.
Workspaces
A credential is not bound to one workspace. The server resolves a workspace per tool call, in this order:
- The
workspaceIdargument on the call — a workspace UUID, or the numeric ID shown in the app. - The
WORKSPACE-IDheader. - The credential’s sole workspace, when it can access exactly one.
Call getWorkspaces first. It’s the only tool that doesn’t need a workspace, and it returns every
workspace the credential can access.
A valid credential that can’t resolve the requested workspace doesn’t get a 401. It gets HTTP 200
with isError: true and a uniform message, identical for an unknown UUID, a workspace you’re not a
member of, and one outside your grant, so the response can’t be used to discover which workspaces
exist.
Rate limits
MCP calls spend from the same weighted per-workspace bucket as /api/v2, at the same prices: a
read tool costs what its root field costs, and every write costs what its mutation costs: the
mutation base plus 1 for each field the tool selects in the payload.
Everything in the Rate limits guide applies here unchanged.