Connect a client

Any MCP client that speaks Streamable HTTP can connect. You need the endpoint and a credential — there is nothing to install and no per-client configuration on Archive’s side.

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

Option 1 — bearer token

The fastest path, and the right one for a server-side agent you run yourself. Provision an API token in the Archive app’s Integration tab — the same token that works against /api/v2 — and send it in the Authorization header.

{
"mcpServers": {
  "archive": {
    "type": "http",
    "url": "https://app.archive.com/api/v2/mcp",
    "headers": {
      "Authorization": "Bearer <your-token>"
    }
  }
}
}

Most clients accept this shape; check yours for the exact key names. If your client cannot send a static header, use OAuth instead.

Option 2 — OAuth 2.1

The right path for a client used by other people, where each person authorizes their own access. Archive is its own authorization server, and the whole flow is discoverable — a compliant client needs only the endpoint URL.

1. The client calls the endpoint without credentials and gets HTTP 401 with a WWW-Authenticate challenge naming the protected-resource metadata URL.
2. It fetches that metadata (RFC 9728), then the authorization-server metadata (RFC 8414).
3. It registers itself if needed via Dynamic Client Registration (RFC 7591) at POST /oauth/register.
4. It sends the person to /oauth/authorize. They log in and consent, choosing whether to grant the optional write scope.
5. It exchanges the authorization code at /oauth/token for an access token and uses that as the bearer credential.

Tokens are opaque and Archive-issued; there is nothing for the client to decode.

Verify the connection

getWorkspaces is the correct first call for any client. It needs no workspace, so it succeeds the moment the credential is valid, and it returns the ids every other tool needs.

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
  "name": "getWorkspaces",
  "arguments": {}
}
}

If it returns HTTP 401, the credential is the problem. If it returns HTTP 200 with isError: true, the credential is valid but something about the request is not — read the message.

What tools/list returns

The list is truthful for your credential: it advertises only tools you can actually call. Two things narrow it.

• Write capability. An OAuth connection without the write scope sees read tools only.
• Alpha gating. Tools behind an alpha feature are omitted unless the request opts in via the X-Archive-Alpha-Features header, and calling one without opting in returns the same response as calling a tool that does not exist. See Alpha features.

So a diff between this documentation and your own tools/list output is expected and meaningful — it tells you what your credential is not authorized for.

Selecting a workspace

Most tools act on one workspace. Pass it explicitly as workspaceId on the call — a workspace UUID or the numeric id from the app — or send a WORKSPACE-ID header. If your credential can reach exactly one workspace, you may omit both.

{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
  "name": "searchItems",
  "arguments": {
    "workspaceId": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    "limit": 20
  }
}
}

Protocol version

The server supports the 2025-03-26 and 2025-06-18 Streamable HTTP revisions. Two separate mechanisms carry a version, and they behave differently — worth keeping apart.

initialize negotiation (the protocolVersion parameter). The server echoes back the version it will speak:

Read the protocolVersion in the initialize result and speak that, rather than assuming your request was honored.

The MCP-Protocol-Version HTTP header. This is recorded but not validated. An unrecognized value is accepted rather than rejected, and a request that omits the header is treated as 2025-03-26 per the transport spec’s backwards-compatibility clause.