Docs · MCP

Use ran inside Claude or ChatGPT.

The MCP connector gives the assistant you already pay for read-only access to everything Margarita keeps current — cited, and only from sources you approve.

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

  • Claude
  • ChatGPT
  • Codex
  • Cursor

Access

Read-only. Scoped to what you approve.

Three things stay true for every app you connect.

Read-only

Four read tools and nothing else. The connector can’t write, delete, send, or act.

Your choice

Pick sources at connect; flip per-source toggles in Settings → MCP any time after. A source turned off disappears from every connected app immediately.

Your plan

The model answering you spends your assistant’s subscription. Margarita’s retrieval per query is metered to your ran account, 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 Settings → Connect your AI (MCP) 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 read-only access, and pick the sources it may see. OAuth 2.1 (PKCE, dynamic client registration) runs automatically.

    No keys to paste.

Tools

Four tools. Read-only, all of them.

They read what Margarita has already organized — snippets and pointers, so your assistant’s subscription isn’t spent on dumps.

search
Ranked snippet search (semantic + keyword) over the sources you approved, with document pointers and source metadata.
read
Section-level reads of one document by id — outline first, then a named section. Never whole-document dumps.
map
The typed connection graph around a named entity — one-hop neighbours with link types.
catalog_route
Where an answer lives (which source), without executing anything.

Read-onlyIdempotentNever a live system

search

Input
query (≤2000 chars); optional topK (1–20, default 8); optional sourceIds (restrict to sources already seen in results).
Output
Ranked hits — document id, title, heading path, snippet (≤700 chars), score, and the source it came from.
Scope
Results only ever come from sources you approved. Naming an out-of-scope source returns a scope error, not data.

read

Input
docId; optional headingPath.
Output
Without headingPath: the document’s section outline (heading paths + sizes) — pointers only. With it: that section’s text.
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.

catalog_route

Input
query.
Output
Up to 12 routes — which connected sources hold material for the question, and whether it’s answerable here or is live state ran answers in-app.

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.
  • Revoke any connected app at any time in Settings → MCP. A source turned off disappears from every app immediately.
  • The full picture is in the privacy policy.

Support

Stuck? A person answers.

Write to hello@thepromptdepartment.org and name the app you’re connecting from.