Connect an MCP client

Readsira runs a Model Context Protocol server, so assistants can search and read your library while you work. The assistant brings its own model: Readsira only returns passages and documents, with a link back to each source.

• Server URL: https://api.readsira.com/mcp
• Transport: Streamable HTTP, stateless (no session to keep)
• Auth: sign in with Readsira (OAuth) for Claude and ChatGPT, or an MCP key sent as Authorization: Bearer pk_... for Claude Code, Cursor and other clients that accept a header. Both reach the same tools, scopes and limits.

Claude (web and desktop)

1. In Claude, open Settings, Connectors and choose Add custom connector.
2. Paste https://api.readsira.com/mcp and add it. Claude opens Readsira in your browser.
3. Sign in if asked. The consent screen shows what Claude asks for in plain words; untick anything you do not want (writing is never needed for search), then choose Allow.
4. Ask Claude to "search my Readsira library for sodium-ion storage".

No key is pasted. The connection appears under Settings, API and MCP, Connected apps.

ChatGPT

1. In ChatGPT, open Settings, Apps and connectors and create a connector (developer mode must be on for custom connectors).
2. Paste https://api.readsira.com/mcp as the server URL and choose OAuth as the authentication.
3. ChatGPT opens Readsira: sign in, review the permissions and choose Allow.
4. Enable the connector in a chat and ask it to search your library.

Menu names in Claude and ChatGPT change from time to time; the server URL and the Readsira consent screen stay the same.

Clients with a header: create an MCP key

In the app, open Settings, API and MCP and choose Create MCP key. The default key can only read (mcp + read:library). Add read:projects to use your projects. Add write:bookmarks or write:notes only if you want the assistant to save links or add notes, and only if you review what it does: text on web pages can try to steer an assistant. Copy the key now; it is shown once.

Add the server to your client

Claude Code

claude mcp add --transport http readsira https://api.readsira.com/mcp \
  --header "Authorization: Bearer pk_your_key"

Then type /mcp in a Claude Code session: readsira shows as connected. Ask "search my Readsira library for sodium-ion storage". This command is tested against the Readsira server before each release (claude mcp list reports it as connected).

Cursor

Add to .cursor/mcp.json in your project, or to Cursor's global MCP settings:

{
  "mcpServers": {
    "readsira": {
      "url": "https://api.readsira.com/mcp",
      "headers": { "Authorization": "Bearer pk_your_key" }
    }
  }
}

Other clients that accept a header

Any client that supports remote MCP servers over Streamable HTTP with custom headers works with the same URL and Authorization header.

Clients that only sign in

A client that supports the MCP authorization spec (OAuth 2.1 with dynamic client registration) needs only the server URL: it discovers Readsira's sign-in from the server, as Claude and ChatGPT do.

Tools

Tool	Scope	What it does
search_library	read:library	Best-matching passages with title, URL, PDF page and media timestamps (query, limit 1-20)
get_document	read:library	A document's text in pages (documentId, bookmarkId or url; offset, maxChars) plus your tags, notes and highlights
list_projects	read:projects	Your projects, most recently active first (status active or archived, limit 1-50)
get_project_context	read:projects	A project's instructions, decided decisions, pinned notes and sources; with query, the best passages from the project (maxChars up to 32,000)
add_bookmark	write:bookmarks	Save a URL; saving one you already have returns created: false and only adds tags. With projectId (also needs write:projects), also adds it to that project
create_note	write:notes	Append a note to one of your saved items (bookmarkId), or add a note to a project (projectId, optional title; needs write:projects); it becomes searchable

Tools your key's scopes do not allow are not listed. get_project_context gives the assistant the project's instructions so it can follow them while it works for you in that project. When the context is longer than maxChars, sources are left out first, then passages, notes and decisions, and the result says truncated: true.

Tool errors come back as tool results with isError: true and a code: SCOPE_REQUIRED, NOT_FOUND, RATE_LIMITED (with retryAfterSeconds), PLAN_REQUIRED, VALIDATION_FAILED, URL_REJECTED, and for project writes PROJECT_LIMIT_REACHED (the plan's items per project) or PROJECT_ARCHIVED. If AI search is paused for the day, search_library still answers with text matching and says degraded: "lexical".

Limits

Plan	MCP keys	Tool calls per day	Calls per hour per key	Tools
Free	1	100	60	read tools
Pro	10	10,000	600	all
Research	10	25,000	1,200	all

Days are UTC. Listing tools does not count; reading a long document counts one call per 12,000 characters, writes count two. All plan limits: Plan limits.

Revoke and review

Settings, API and MCP, Connected apps lists every app you allowed with its permissions, when it connected and when it last used your library. Disconnect stops it at once (its next call is refused); to use it again, connect it again from the app. You get an in-app notice each time an app connects, so an unexpected connection is visible.

The same page lists every key with its last use and client, and an Activity table of every tool call (time, tool, status, client, number of results). Readsira never records your search text or note text there. Revoke stops a key at once. The first time a key is used you get an in-app notice naming the client, so an unexpected use is visible.

For client developers: OAuth details

Readsira is its own authorization server, following the MCP authorization spec:

What	Value
Protected resource metadata (RFC 9728)	https://api.readsira.com/.well-known/oauth-protected-resource/mcp
Authorization server metadata (8414)	https://api.readsira.com/.well-known/oauth-authorization-server
Dynamic client registration (7591)	POST /oauth/register; public clients (none) or client_secret_post / _basic
Authorization	GET /oauth/authorize, code flow with PKCE S256 only (plain is refused), state required
Token	POST /oauth/token: authorization_code, refresh_token
Revocation (7009)	POST /oauth/revoke
Scopes	read:library (default), read:projects, write:projects, write:bookmarks, write:notes

• A 401 from /mcp carries WWW-Authenticate: Bearer resource_metadata="...", so clients can start discovery from the server URL.
• Redirect URIs must be registered and are matched exactly: https, or http on 127.0.0.1, localhost or [::1] for native apps.
• The authorization response carries iss (RFC 9207). Codes live 60 seconds and work once.
• Access tokens live one hour. Refresh tokens rotate on every use; presenting a used refresh token again revokes the whole connection.
• Tokens are for the MCP server only; the REST API takes API keys.
• Registration is rate limited per IP address, and registered clients that are not used for 30 days are removed.