Tephra

Tephra MCP

[Tephra MCP server]

Documentation and config examples for Tephra, a hosted remote MCP server: one memory your AI tools share, tied to your account. Tools you connect recall from it and add to it. Besides documentation and configuration examples, it holds a small optional stdio bridge (bin/, test/, package.json, MIT) for AI apps that only speak stdio. Tephra itself is a paid hosted service by Obsidian Metrics.

• Server URL (Streamable HTTP): https://tephra.obsidian-metrics.com/mcp
• Connecting: add the server URL. Clients that support MCP OAuth sign in with your Obsidian account from the client; for others, use a personal AI key (tpk_...). Sign-in support varies by client, so check the connect guide for yours.
• Connect guide: CONNECT.md and https://tephra.obsidian-metrics.com/connect
• Registry metadata: server.json; client config examples: mcp-config-examples.json

Features

• One memory your AI tools share. The connect page has steps for Claude (claude.ai, Desktop and mobile), ChatGPT, VS Code (GitHub Copilot), Cursor, Claude Code, Gemini CLI, Windsurf, Zed, Mistral Le Chat, Perplexity and any other app that can add a remote MCP server. Each connected tool recalls from the same memory and adds to it.
• Three MCP tools (a read-only key gets only the first two):
  • tephra_recall: ranked recall over your memory plus the shared library. query up to 4000 characters; limit 1-50 (default 10); optional keywords (up to 20 exact terms for the keyword arm), mode (semantic, keyword or hybrid) and reader_order: "chronological" (same rows oldest-first, each dated).
  • tephra_search: plain semantic search over the same memory, without recall's ranking extras. query up to 4000 characters; limit 1-100 (default 10).
  • tephra_remember: save one memory to your own account, never to the shared library. text up to 8000 characters; optional region (leave it out and Tephra files it), up to 10 tags, importance 1-5 (default 3). Tephra adds a via-ai-key tag and reports when the memory was already stored.
• Tephra's directions on MCP: recall, search and remember results can include a <tephra_directions> block with the same guidance Tephra's REST API returns: a recall-then-save directive, a warning (flagged blocked) when a save was made without a recent recall, a completeness note, the summary sheet and the "you may be missing" list. The summary sheet, the missing list and alerts index stored records and are fenced and labelled as data, not instructions. The server's initialize instructions ask the AI to call tephra_recall before answering questions that may depend on saved context and tephra_remember to save durable facts; the AI still decides when to call the tools.
• Hybrid recall: bge-m3 semantic search and a keyword arm fused by reciprocal rank, a cross-encoder rerank, and a bounded two-hop walk over linked memories.
• Account-scoped by default: each member is their own tenant; everything a member saves is tied to their account and is not visible to other members.
• Shared library: public knowledge (no member data), grown hourly from sources such as arXiv, PubMed, Federal Register and Crossref/OpenAlex; recall draws on it alongside your own memories.
• Control and audit: up to 10 active AI keys, each revocable, optionally read-only, with its own activity log; a connected-apps panel to disconnect OAuth apps; edit history, edit/delete/contest a memory, data export (app).
• Prompt-injection hardening on key/MCP results: invisible characters stripped, records capped at 4000 characters, results wrapped as notes-not-instructions.
• Remote streamable-HTTP MCP, hosted on Cloudflare Workers; nothing to self-host; the stdio bridge below is optional.

Optional stdio bridge

Most AI apps connect to Tephra directly with the server URL above. For an app that only speaks stdio, this repository ships a bridge (bin/tephra-mcp.mjs, MIT) that starts mcp-remote (pinned to 0.15.2, published 2026-10-20 with GitHub provenance) pointed at https://tephra.obsidian-metrics.com/mcp:

npx -y github:andylang598/tephra-mcp#v1.0.0

Only this github: form is official; the names tephra-mcp and tephra-mcp-bridge are not registered on npm. Use the tag, not the default branch: npm ignores this repository's lockfile for git installs, so mcp-remote is exact but its own dependencies resolve within their version ranges when you install (the committed package-lock.json applies to npm ci from a clone). npx -y github:andylang598/tephra-mcp#v1.0.0 --print-config shows the one URL the bridge would use without connecting.

• Sign-in is Tephra's own OAuth 2.1 flow, run by mcp-remote in your browser. The bridge's own code never handles a password, key or token. mcp-remote keeps the sign-in tokens it receives in ~/.mcp-auth on your machine (owner-only file mode); delete that folder to sign out.
• The bridge accepts one MCP URL, https://tephra.obsidian-metrics.com/mcp, and refuses any other host, scheme, port or path, and any argument except --print-config. The child process inherits your environment, so proxy and certificate settings you have set apply to it.
• The mcprush security grade for Tephra covers this bridge's source and its dependency tree as installed. It is not a review of the Tephra service, which runs at its own address.
• Tests: npm test from a clone (offline). Node 20.18.1 or newer.

Limits

• Tephra is a paid product: no free tier. Access is Premium ($19/mo at the member rate through the Obsidian Metrics community, $29/mo direct) or a $399 one-time Tephra seat with no subscription; no usage metering. Keys and connections pause if the membership lapses.
• Rate limits: 60 requests per minute per AI key or connected app, plus a member-wide cap of 120 per minute.
• The AI must call tephra_remember; Tephra does not auto-capture chats and has no Gmail/Slack/Drive connectors.
• No image/audio ingest. Members cannot publish into the shared library.

Benchmark

LongMemEval-S, all 500 questions, top-10 retrieval, gpt-4o-2024-08-06 judge, one run: 85.2% with a gpt-4o reader; 95.2% with a Claude Opus 5.5 reader (run via Claude Code sub-agents); same retrieval. Retrieval had at least one needed session in the top 10 for 467 of 470, and all needed sessions for 435. Not a ranking.