Docs · MCP

Use ran inside Claude or ChatGPT.

The MCP connector gives the assistant you already pay for access to everything ran keeps current — it reads, cited, only from sources you approve, and adds documents only if the app asks and you leave that tick on.

Connection URLhttps://app.ran-stack.com/api/mcp

  • Claude
  • ChatGPT
  • Codex
  • Cursor

Access

Never acts in your tools. Scoped to what you approve.

Three things stay true for every app you connect.

Never acts in your tools

The read tools are always on. If the app asks to add documents, that’s a separate tick on the consent page, ticked unless you untick it — and nothing the connector does can edit, delete, send, or act in your tools.

Your choice

Pick sources at connect — the consent ticks are the only control. Disconnecting a source in ran removes it from every connected app immediately; there is no separate per-app switch.

Your subscription

The model answering you spends your assistant’s subscription. ran’s retrieval per query counts toward your ran usage, as usual.

Setup

Connected in a minute.

Copy one URL, approve on connect — no keys to paste.

  1. 01

    Copy the connection URL

    In ran, open Add ran to Claude and copy https://app.ran-stack.com/api/mcp.

    One URL, the same for every app.

  2. 02

    Add it in your app

    Add a custom connector / MCP server with that URL. Transport: Streamable HTTP.

    Claude, ChatGPT, Codex, Cursor.

  3. 03

    Approve on connect

    Your app opens a ran page — sign in, approve access (search and read, plus adding documents if the app asks and you leave that tick on), and pick the sources it may see. OAuth 2.1 (PKCE, dynamic client registration) runs automatically.

    No keys to paste.

Tools

Five tools. Four read, one opt-in write.

recall answers from what ran has already organized — cited facts, passages and pointers, so your assistant’s subscription isn’t spent on dumps. inbox shows what ran noticed while you were away. upload only adds, and only with your tick.

recall
The entry point: one call returns the facts ran extracted and cited passages across every source you approved, with an answerability verdict and anything that conflicts.
read
Drill-down after recall: one passage’s full text, one section, or a document’s outline. Never whole-document dumps.
map
Drill-down after recall: the typed connection graph around a named entity — one-hop neighbours with link types.
inbox
What ran noticed while you were away — contradictions between your sources, notes a newer source overtook, threads waiting on your reply. Every other tool also carries a short “needs you” note when something is due, shown once.
upload
Only with the memory:write scope: saves text, or a public web page by URL, into your Uploads, noted as added by a connected app — and the app can read back what connected apps added, unless you untick “Uploads added by connected apps” on the consent page.

Never acts in your toolsCited passagesNo edits or deletes

recall

Input
question (≤2000 chars, never a source name); optional topK (1–12, default 6).
Output
Facts extracted when your sources were indexed — each with a ref (F1, F2 …), its value, date, document and source link, marked current, stale or disputed when another source disagrees — then ranked passages, each with a ref (S1, S2 …), document, section, source link, chunk id and last-updated date — plus answerability (cited / partial / abstain), conflicts and related documents.
Scope
Facts and passages only ever come from sources you approved — plus, when the connection may add documents, what connected apps added to your Uploads.

read

Input
docId; optional chunkId or headingPath.
Output
With chunkId: that passage’s full text. With headingPath: that section’s text. With neither: the section outline.
Limit
Sections cap at 8,000 chars with a truncated flag. Whole-document dumps are not available.

map

Input
name (a document title or stem).
Output
The resolved node plus up to 40 one-hop neighbours, each with link type and direction.
Edge
Ambiguous names return the candidate list — never a silent first match. Unknown names return a clear not-found.

inbox

Input
None.
Output
The items due now — each shown once — and the ones shown in the last 7 days, each with what it is about and the documents involved.
Scope
Only your own items, from your own workspace, about documents this connection may see.

upload

Input
title plus exactly one of text or url (a public http(s) page: HTML, markdown, or plain text).
Scope
Needs memory:write. A read-only connection gets a scope error and nothing is written.
Limit
The Upload cap applies (4 MB). At most 30 uploads an hour and 200 a day, two at a time; connected apps can keep up to 1,000 documents (100 MB) in your memory; and new uploads pause once your workspace reaches its monthly upload indexing limit (about 500 million tokens of new text a month), while search keeps working. Text only — add PDFs, Word and Excel files in ran under Connections → Uploads. Only public pages on ports 80 and 443 are fetched; private and internal network addresses never are. A page added by URL keeps that URL on the document.
Edge
Not idempotent for URLs: the same page fetched later may differ and land as a new document. Identical content answers unchanged.

Trust

Scoped at consent. Revocable any time.

The consent you grant on connect is pinned server-side and enforced on every call.

  • OAuth 2.1 with PKCE (S256) and mandatory Dynamic Client Registration (RFC 7591), plus Resource Indicators (RFC 8707). Protected Resource Metadata (RFC 9728) lives at https://app.ran-stack.com/.well-known/oauth-protected-resource.
  • Access tokens are opaque and stored only as SHA-256 hashes. Refresh tokens rotate on every use — replay revokes the whole authorization.
  • Scope is pinned at consent: your account, and only the sources you approved. It is never selectable by the client.
  • Two scopes. mcp:read is always granted: search and read the sources you ticked. memory:write lets the app add documents to your Uploads, each noted as added by a connected app, and read back what connected apps added, unless you untick “Uploads added by connected apps” on the consent page — never the files you uploaded yourself, or any other source, unless you ticked them. It is only offered when the app asks for it, as its own tick on the consent page, ticked unless you untick it; untick it and the connection stays read-only. The ticks are the control.
  • Revoke any connected app at any time under Add ran to Claude in ran. Disconnecting a source removes it from every app immediately.
  • The full picture is in the privacy policy.

Support

Stuck? A person answers.

Write to gabrielezerzer.zam@gmail.com and name the app you’re connecting from.