AI Agents and API

Recalio exposes your library to software two ways: a hosted MCP endpoint that AI tools connect to over a URL, and the REST API underneath it. MCP never exposes deletion; REST callers only receive it when you explicitly grant a key the Documents: Delete scope.

Connect an AI agent

The endpoint is:

https://api.recalio.com/mcp

Nothing to install, and no key to paste: the endpoint speaks OAuth, so the client signs you in.

Most clients take a JSON block like this — the URL and nothing else:

{
  "mcpServers": {
    "recalio": {
      "url": "https://api.recalio.com/mcp"
    }
  }
}

Claude Code adds it in one command:

claude mcp add --transport http recalio https://api.recalio.com/mcp

Claude Code uses Recalio’s reviewed OAuth flow. Recalio does not enable public Dynamic Client Registration. Cursor, VS Code, and Windsurf can use the API-key configuration below when they support a private static Authorization header. Claude Desktop and Claude.ai managed connectors are not supported until their OAuth clients complete production review; do not place a personal key in an organization-shared connector.

The first time the client connects, Recalio refuses the request and points it at sign-in. Your browser opens, you sign in to Recalio, and a consent screen names the app asking for access. Approve it and the client holds a token from then on; you never handle a secret.

Once connected, seven tools appear:

• search — search saved documents and feeds
• list-documents — list the inbox or archive, with filters and paging
• get-document — one document with its full text, note, and highlights
• list-highlights — highlights grouped by document
• save-url — save a link
• update-document — archive, restore, mark read or unread, set the note
• update-highlight — set the note on a highlight

A connected agent can read your library, save links, archive, and write notes. It cannot delete a document or a highlight, and it cannot touch your account, billing, or email settings — that limit is enforced on our side, not by the client.

To disconnect, remove the server or connector in the client. If the client offers a separate Disconnect or Revoke authorization action, use it before removing the configuration.

Connect with an API key instead

Scripts, cron jobs, and clients that only send a static header can use a key instead of OAuth.

1. Open Settings in Recalio and find API keys.
2. Click Create API key, name it, and choose scopes.
3. Copy the secret. It is shown once.

For the full agent surface, select:

• Documents: Read, Save, Update
• Highlights: Read, Update
• Feeds: Read — search covers feeds too, so search fails without it

Leave Documents: Delete unchecked unless you want scripted deletion. The MCP tools never delete anything, with or without that scope.

Then send it as a bearer token:

{
  "mcpServers": {
    "recalio": {
      "url": "https://api.recalio.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Revoke a key from the same screen. Revoking takes effect immediately.

Useful things to ask for once it is connected:

• “What’s in my Recalio inbox from this week?”
• “Find what I saved about retrieval-augmented generation and quote the highlights.”
• “Save these three links and archive everything I already read.”

Call the API directly

Anything the tools do, you can do yourself against https://api.recalio.com, with an API key as the bearer token.

export AUTH="Authorization: Bearer <your-api-key>"

# What's waiting
curl -H "$AUTH" "https://api.recalio.com/api/v1/documents?limit=10"

# Search documents and feeds
curl -H "$AUTH" "https://api.recalio.com/api/v1/search?q=spaced+repetition"

# One document, with its parsed text
curl -H "$AUTH" "https://api.recalio.com/api/v1/documents/<document-id>"

# Save a link
curl -H "$AUTH" -H "content-type: application/json" \
  -d '{"url":"https://example.com/essay"}' \
  "https://api.recalio.com/api/v1/documents"

# Archive it
curl -X PATCH -H "$AUTH" -H "content-type: application/json" \
  -d '{"collectionStatus":"archive"}' \
  "https://api.recalio.com/api/v1/documents/<document-id>"

# Your highlights
curl -H "$AUTH" "https://api.recalio.com/api/v1/highlights?limit=20"

List endpoints return { items, nextCursor }. Pass nextCursor back as ?cursor= to page. Errors come back as { error: { code, message, requestId } } with a matching HTTP status.

Troubleshooting

The client never asks me to sign in — first remove any stale or empty Authorization header. Claude Code should then fall back to OAuth. A client with private static-header support can use the API-key configuration above; managed Claude connectors remain unsupported until their OAuth registration is reviewed.

Auth errors on every tool call — the connection was revoked, or the key was. Reconnect the server in the client, or issue a new key.

“Missing required API key scope” — an API-key caller lacks a scope that tool needs. Keys cannot be edited; create a new one with the right scopes and revoke the old one. OAuth connections always carry the full tool surface.

Search fails while lists work — the key is missing Feeds: Read.

A saved article has empty content — parsing runs after the save returns. Fetch the document again in a few seconds.

Self-hosted or staging backend — point clients at that host instead: its /mcp path for agents, its /api/v1 prefix for HTTP calls.