# MCP overview

Archive runs a [Model Context Protocol](https://modelcontextprotocol.io) 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.

```http
POST https://app.archive.com/api/v2/mcp
```

The 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 **33 read tools** and **31 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](/api/v2/docs/mcp/read-tools) — the 33 tools that only fetch data.
- [Write tools](/api/v2/docs/mcp/write-tools) — the 31 tools that change something.
- [Agent conventions](/api/v2/docs/mcp/conventions) — the rules that apply across every tool.

## 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](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata and [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) authorization-server metadata, and supports [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591) Dynamic Client Registration, so a compliant client can discover and register on its own. See [Connect a client](/api/v2/docs/mcp/connect).

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.

> **Authentication errors are uniform**
>
> Every authentication failure returns the same message, whether the token is missing, malformed, revoked, or disabled. This is intentional: it prevents the response from revealing which check failed. Workspace authorization is a separate class, described next.

## Workspaces

A credential is not bound to one workspace. The server resolves a workspace per tool call, in this order:

1. The `workspaceId` argument on the call — a workspace UUID, or the numeric ID shown in the app.
2. The `WORKSPACE-ID` header.
3. 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 charges the flat mutation cost. Everything in the [Rate limits guide](/api/v2/docs/guides/rate-limits) applies here unchanged.

## What is not listed here

> **Alpha tools**
>
> Some surfaces are still in alpha and gated behind the `X-Archive-Alpha-Features` opt-in header (currently campaign\_creator\_views). Their tools are omitted from `tools/list` and rejected on call unless your request opts in, so these pages describe exactly what a client without the opt-in sees. Alpha surfaces carry no stability contract; see [Alpha features](/api/v2/docs/guides/alpha-features).