MCP overview
Archive ships a Model Context Protocol server so an AI agent can work with your data directly — searching content, reading creator profiles, and managing saved views without you writing a GraphQL client.
It is the same product surface as /api/v2, in a different shape. Every tool wraps exactly one
public GraphQL root field and executes it verbatim: 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 to reason about.
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 32 read tools and 31 write tools. The mapping to GraphQL is
exhaustive in both directions: every public query and mutation has exactly one tool, and every tool
points at exactly one public field. If you can do it on /api/v2, you can do it over MCP — and each
operation’s reference page links to the tool that wraps it.
Names follow the GraphQL field in camelCase, except where an agent reads the intent better: 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 32 tools that only fetch data.
- Write tools — the 31 tools that change something.
- Agent conventions — the rules that hold across every tool.
Authentication
The endpoint accepts two credential types, tried in that order:
| Credential | How you get it | Write access |
|---|---|---|
| Bearer token | The same API token you use for /api/v2, provisioned in the Integration tab | Yes — parity with /api/v2, where any valid token may 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 reach exactly one.
Call getWorkspaces first. It is the one tool that needs no workspace, and it returns every
workspace the credential can reach.
A valid credential that cannot resolve the requested workspace does not get a 401. It gets HTTP
200 with isError: true and a uniform message — identical for an unknown UUID, a workspace you are
not a member of, and one outside your grant, so the response is not an enumeration oracle.
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 charges the flat mutation cost. Everything in
the Rate limits guide applies here unchanged.