MCP Server

Overview

The Relinkia MCP server exposes your personal knowledge graph as structured memory for AI tools. Claude can query your notes, concepts, and connections directly — without you having to copy-paste content into the conversation.

In standard mode, two tools are available to Claude once the server is connected:

Requirements

Setup

Claude Desktop

First, generate an API token: Relinkia → Settings → Integrations → Generate MCP token. Then edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "relinkia": {
      "command": "npx",
      "args": ["-y", "@relinkia/mcp-server"],
      "env": {
        "RELINKIA_API_TOKEN": "<your-api-token>"
      }
    }
  }
}

Claude.ai (Remote MCP)

Claude.ai uses OAuth to connect to Remote MCP servers — no API token needed. Go to Settings → Integrations → Add MCP server and follow these steps:

1. Enter https://mcp.relinkia.app/sse as the server URL.
2. Click Add — claude.ai automatically initiates the OAuth authorization flow.
3. A Relinkia login and consent page opens in your browser.
4. Log in to Relinkia (if not already logged in) and click Approve.
5. You are redirected back to claude.ai — Relinkia tools are now available.

LangChain, n8n, or custom agents (REST)

The same tools are exposed over a standard REST API for non-MCP clients:

Base URL : https://api.relinkia.app/api/v1/agent/
Auth     : Authorization: Bearer <your-api-token>
Schema   : /api/v1/agent/openapi.json

relinkia_search

Semantic search across your knowledge base. Uses a hybrid pipeline (full-text + vector embeddings + Cohere reranking).

Parameters

relinkia_get_context

Context-aware search enriched by the current conversation. Same pipeline as relinkia_search, but the embedding and reranking are augmented by a conversation summary you provide.

Parameters

relinkia_get_context({
  q: "productive failure and learning",
  conversation_context: "Discussion on rethinking school assessment
    as a calibrated stimulus rather than a sanction. Parallel with
    Taleb's antifragility applied to education. Question about
    graduated exposure to error.",
  limit: 5
})

Understanding responses

Sources

Both tools return a sources array. Each source includes a title, a URL back to your note, a role, and the date it was last updated. Claude cites these as links — never as verbatim quotes.

"sources": [
  {
    "title": "Calibrated friction as stimulus",
    "url": "https://relinkia.app/note/{id}",
    "role": "argument_central",
    "last_updated": "2026-02-11"
  }
]

Possible roles: argument_central, external_source, emerging_connection, counter_argument.

Temporal advisory

If a retrieved note has been superseded by a more recent one, the response includes a temporal_advisory. Claude will surface this before drawing on the older note — to avoid presenting an abandoned position as your current thinking.

"temporal_advisory": "The most recent note on this point
  (11 February) nuances what you wrote in November.
  Mention this before relying on the older note."

Disambiguation

When a query matches several distinct clusters without a clear dominant match, relinkia_get_context returns a disambiguation_needed status instead of guessing. Claude will then ask you which thread to follow before answering.

{
  "status": "disambiguation_needed",
  "interpretations": [
    {
      "cluster": "Antifragility in finance",
      "note_count": 4,
      "hint": "Taleb notes, hedging, optionality"
    },
    {
      "cluster": "Antifragility in education",
      "note_count": 7,
      "hint": "More recent — graduated exposure to error"
    }
  ],
  "message_to_display": "You have two distinct threads on
    antifragility. Which one should I connect to our discussion?"
}

Quotas

Agent calls that trigger AI work draw from the same daily gesture quota as in-app gestures — there is no separate agent quota. Plain note search does not count as a gesture.

* With BYOK, there is no daily limit: only an anti-abuse safety cap of 300 AI actions per day applies. MCP tools do not use your personal Anthropic key: they make no call to Anthropic. Their search and retrieval run on the Relinkia RAG infrastructure (embeddings, vector search, reranking), covered by the platform fee, and the background processing they trigger (concept extraction, discoveries) runs on Relinkia's accounts.

Owner Mode

Owner mode unlocks ten tools for account owners who want to use a personal AI agent to read and write their knowledge base directly. Unlike the standard mode — which returns gists and metadata — owner mode gives the agent access to the full text of notes and the ability to create or update them.

Typical use cases: maintaining a structured knowledge base with an AI assistant, syncing notes from external sources, or running automated pipelines that enrich your graph overnight.

Authentication

Owner mode requires a dedicated owner token — separate from the standard API token. Generate it in: Settings → Integrations → Generate owner token.

Pass it as a Bearer token in the Authorization header:

Authorization: Bearer <your-owner-token>

For Claude Desktop or MCP server config, use the RELINKIA_OWNER_TOKEN env variable:

{
  "mcpServers": {
    "relinkia-owner": {
      "command": "npx",
      "args": ["-y", "@relinkia/mcp-server"],
      "env": {
        "RELINKIA_OWNER_TOKEN": "<your-owner-token>"
      }
    }
  }
}

The _context block

Every owner tool response carries a _context block. It tells the agent whether the scope exists and which canonical documents it holds, ranked for the current request.

Canonical document. A canonical document is a reference document of the scope: a note with a docKey whose type is synthesis, index or decision, or that is explicitly marked canonical: true. A docKey alone makes a note addressable (get_by_doc_key, update_canonical, supersession), not canonical: an addressable question, journal or contact note is not listed in canonicalDocs. A synthesis or index marked canonical: false is not listed either; a decision is always canonical. Set the status with the canonical parameter of create_note and update_note_metadata.

"_context": {
  "scope": { "name": "project-x", "exists": true, "noteCount": 12, "decisionCount": 3 },
  "canonicalDocs": [
    { "docKey": "project-x-decisions", "title": "Decisions", "type": "index",
      "currentVersion": 2, "updatedAt": "2026-10-17T16:05:00.000Z", "isDecision": false,
      "relevanceScore": 0.41, "embeddingStatus": "ready", "pinned": true },
    { "docKey": "project-x-architecture", "title": "Architecture", "type": "synthesis",
      "currentVersion": 3, "updatedAt": "2026-10-18T09:12:00.000Z", "isDecision": false,
      "relevanceScore": 0.82, "embeddingStatus": "ready" },
    { "docKey": "project-x-sources", "title": "Sources", "type": "index", "currentVersion": 1,
      "updatedAt": "2026-10-18T09:40:00.000Z", "isDecision": false,
      "relevanceScore": null, "embeddingStatus": "pending" }
  ],
  "canonicalDocsTruncated": false,
  "canonicalDocsRanking": "relevance",
  "serverTime": "2026-10-18T09:41:02.000Z",
  "protocolVersion": "canonical-docs/0.7"
}

Order of documents. In a relevance ranking, documents with a score come first, highest score first; documents without a score follow, most recently updated first — they are never sorted as a score of 0. In a recency ranking, every document is ordered by update date. In both cases, the document the tool addresses directly (the docKey of create_note, get_by_doc_key, update_canonical or update_note_metadata) stays first, with or without a score, and carries pinned: true — a document you have just created is therefore always in the response, even in a scope with more than 20 canonical documents.

Two rankings. search_notes and canonicalDocs answer two different questions. search_notes is a keyword search: it finds the notes of the scope, of any type, that contain the words of the query, ranked by full-text relevance. canonicalDocs lists only the canonical documents, ranked by meaning (semantic similarity) to the request. The two orders differ by design: a note can be first in one and low or absent in the other, and neither order is wrong. Use search_notes for words, names and exact terms, and to go through every match; use canonicalDocs to find the reference document closest in meaning to your task.

The block may be cached for up to 60 seconds: a document can still show pending for that long after its indexing has finished. Every write through the owner tools refreshes it immediately.

get_note_full

Retrieves the complete text content of a note by ID or document key. Returns the full body as a concatenation of all sections — unlike the standard search tools which return only gists.

Parameters

Response

{
  "noteId": "...",
  "title": "Architecture decisions",
  "body": "We chose event sourcing because...",
  "scope": "project-x",
  "docKey": "project-x-architecture",
  "type": "note",
  "currentVersion": 3
}

search_notes

Keyword (full-text) search across owner notes within a scope — not the semantic ranking of canonicalDocs (see Two rankings above). Returns at most limit results per page (default 20, maximum 50), each with its noteId, title, docKey, score and a gist: the beginning of the note, at most 500 characters, with gistTruncated: true when the note is longer. Use get_note_full to fetch the full body of a specific result.

Pages. count is the number of results in the page. hasMore: true means more results exist: pass nextCursor as cursor, with the same q and scope, to get the next page, without duplicates or gaps as long as the scope does not change. nextCursor is null on the last page. A list that ends with hasMore: true is not the whole answer.

Score and order. The score is relative to the query: 1 for the best match of the query, the others as a fraction of it, between 0 and 1, on a scale fixed by the first page and kept on the following pages. It is not comparable between two queries. The score of search_notes and the relevanceScore of canonicalDocs are two different scales and must not be compared to each other. Results with the same score are ordered by noteId ascending, so the same call always returns the same order.

Parameters

{
  "items": [
    { "noteId": "683e4a2f1c9b...", "title": "Research report", "docKey": "ia-report",
      "score": 1, "gist": "The first 500 characters of the note…", "gistTruncated": true },
    { "noteId": "683e4b071d2a...", "title": "Reading notes", "docKey": null,
      "score": 0.62, "gist": "Hippocampus and memory consolidation…", "gistTruncated": false }
  ],
  "count": 2,
  "limit": 2,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJvIjoyLCJoIjoi...",
  "_context": { ... }
}

get_by_doc_key

Retrieves a note by its document key (slug). Useful for deterministic access to well-known notes such as journals, configuration notes, or index pages.

Parameters

Returns the same format as get_note_full.

create_note

Creates a new note in the owner’s knowledge base. Returns the generated note ID and the type actually stored. Optionally assigns a permanent document key for future deterministic access.

Parameters

Response

HTTP 201
{ "noteId": "683e4a2f1c9b...", "storedType": "synthesis" }

storedType is the type actually stored, after alias resolution: note → permanent, source → literature.

Over MCP, create_note returns the same fields plus the context envelope:

{
  "noteId": "683e4a2f1c9b...",
  "storedType": "synthesis",
  "_context": { "protocolVersion": "canonical-docs/0.7", "scope": { ... }, "canonicalDocs": [ ... ] }
}

_context.protocolVersion is canonical-docs/0.7: the version of the context envelope carried by every tool response, distinct from the version of the capabilities descriptor (canonical-docs/0.2).

Errors

update_canonical

Replaces the body of an existing note addressable by docKey, canonical or not (the response field canonical gives its effective canonical status). Uses optimistic concurrency: the server rejects the update if the note has been modified since you last read it. This prevents overwriting changes made by another agent or by the user in the app.

Parameters

Response

HTTP 200
{ "noteId": "683e4a2f1c9b...", "currentVersion": 4, "scope": "project-x",
  "docKey": "project-x-architecture", "canonical": true }

Errors

update_note_metadata

Changes the metadata of an existing note without touching its body. The metadata fields are type, to fix a note imported with the wrong type, and canonical, to set whether the note is a canonical document; send one or both in one call. The note keeps its docKey, title, body, scope, links and tags; it gets a new version and a new history entry. Any note of yours can be changed, with or without a docKey, except decisions (a decision is always canonical). MCP only.

It uses the same optimistic concurrency as update_canonical: read the note with get_note_full (currentVersion, type) immediately before writing, and pass that version as baseVersion. Any other field than noteId, baseVersion, type, canonical and lastWriter is refused with VALIDATION.

The new type is part of the indexed text and of every vector point, and it selects how a long note is split: a successful change re-indexes the whole note. Until the indexing is done, the note shows embeddingStatus: pending in _context, where it is pinned first when it is canonical. Requesting the values the note already has writes nothing and returns changed: false with the current version. If the note shows embeddingStatus: failed after a change, do not call the tool again: the type is already written and the indexing is resumed automatically.

Parameters

Response

{
  "noteId": "683e4a2f1c9b...",
  "currentVersion": 4,
  "storedType": "synthesis",
  "changed": true,
  "canonical": true,
  "_context": { "protocolVersion": "canonical-docs/0.7", "scope": { ... }, "canonicalDocs": [ ... ] }
}

Errors

list_scopes

Lists all scopes in the knowledge base with their volumetry — number of notes and decisions per scope.

Parameters

This tool takes no parameters.

Response

[
  { "scope": "project-x", "noteCount": 12, "decisionCount": 3 },
  { "scope": "architecture", "noteCount": 8, "decisionCount": 1 }
]

Decisions

Decisions are a distinct knowledge type from canonical notes. Where a canonical note can be superseded by a newer document, a decision is never superseded — it is only revised. Every revision is appended to a history[] array, preserving the full audit trail.

Use decisions to record choices that need a stable, auditable history — such as architectural decisions, configuration choices, or team agreements. Use canonical notes for knowledge that evolves and may be replaced.

create_decision

Creates a new decision with a stable semantic key. The key is immutable after creation and must be unique within the scope.

Parameters

Errors

update_decision

Revises an existing decision. The previous body is appended to history[] — decisions are append-only. Uses optimistic concurrency via baseVersion.

Parameters

Errors

get_decision

Returns the current body of a decision and its full revision history.

Parameters

Response

{
  "decisionKey": "auth-protocol",
  "scope": "architecture",
  "currentBody": "We use JWT with 1h expiry...",
  "currentVersion": 2,
  "updatedAt": "2026-07-15T10:23:00Z",
  "history": [
    {
      "version": 1,
      "body": "We use session cookies...",
      "updatedAt": "2026-06-01T08:00:00Z",
      "lastWriter": "claude-code"
    }
  ]
}

list_decisions

Lists all decisions in a scope with their current version and last update time.

Parameters

Response

[
  {
    "decisionKey": "auth-protocol",
    "currentVersion": 2,
    "updatedAt": "2026-07-15T10:23:00Z",
    "lastWriter": "claude-code",
    "summary": "Authentication protocol choice — JWT vs session cookies"
  }
]

Capabilities descriptor

Agents can query this endpoint at startup to discover what the server supports and adapt their behaviour accordingly — for example, skipping write calls if writeEnabled is false.

GET /api/ai/capabilities
Authorization: Bearer <your-owner-token>

{
  "protocolVersion": "canonical-docs/0.2",
  "principal": "owner",
  "ownerMode": true,
  "fullReadEnabled": true,
  "writeEnabled": true,
  "supportedOperations": ["create_note", "update_canonical", "update_note_metadata", "list_scopes"],
  "contextEnvelopeEnabled": true,
  "scopeGrammar": "^[a-z0-9]+(-[a-z0-9]+)*$",
  "creatableNoteTypes": ["fleeting", "literature", "permanent", "index", "project", "synthesis", "question"],
  "noteTypeAliases": { "note": "permanent", "source": "literature" }
}