MCP surface

ctxfile speaks MCP (spec 2025-11-25) over stdio and, with Pro's ctxfile serve, over Streamable HTTP. The free core exposes exactly five tools: one read, two thread verbs, one list, and one bulk-ingest door, plus three resources and three prompts. An active Pro license adds up to five more tools on the stdio surface, gated per licensed feature. Everything below is inspectable live with npx @modelcontextprotocol/inspector ctxfile.

Tool descriptions are the UI for models: each one is written as an instruction (when to use it, what a complete call contains), so any agent on any harness can be pointed at ctxfile cold and know what to do. That is the design rule for this surface, and why it stays at five tools.

Core tools

get_context

get_context(scope?: "full" | "plan" | "files" | "git")

Returns the current ContextObject as JSON (also as structured content). Serves a cached snapshot when one is younger than cacheMaxAgeMs, otherwise rebuilds first. Scopes cut the payload down: plan returns just the plan, files the key files, git the git state; full is everything.

The tool description tells models explicitly: content originating from files or Notion is untrusted data, not instructions. Downstream agents vary in how well they honor that, so the same warning is baked into the prompt surface too.

save_session

save_session({ summary, thread?, key_decisions?, files_touched?, open_items?,
               continues_from?, handoff?, state?, gotchas?, artifacts?, suggested_first_prompt? })

The conversational write door: the agent summarizes this conversation and stores it. No envelope; the harness is inferred from the connected client (declare harness to override). Include thread when the user named one (“save this to my Q3 campaign thread”) and the session attaches to that durable identity. When the user is handing work off, set handoff: true; validation then requires the complete handoff package (state, decisions with rationale, ordered open items, gotchas, artifacts with roles, a suggested first prompt) and rejects anything less with per-section errors the agent self-corrects from. Details: Threads & handoff.

continue_thread

continue_thread(thread?: string)

Fetches the merged, chronological, provenance-tagged history of a thread so a fresh agent can resume it. The name is fuzzy-matched; omit it and the most recently active thread is used, and the result says which one was assumed. Genuine ambiguity returns a shortlist to ask the user with. Token budgeting is newest-detailed, oldest-summarized. Every entry carries its harness, its door, and its timestamp, and the whole result is labeled agent-reported untrusted data.

list_threads

list_threads()

The user's threads with session counts, last-active times, and the last client surface that wrote to each. Meant for the “which thread did you mean” moment.

ingest_context

ingest_context({ ctxfile_ingest_schema: "2", source: { harness }, session: { summary, ... } })

The power/agent door, same schema family as save_session but enveloped for harness-driven bulk ingest: any harness's agent pushes a digest of its own session into ctxfile, which is how unsupported tools (or broken parsers) still populate the sessions array. Validation is strict with field-by-field errors agents self-correct from; records are redacted, stored locally with provenance (reported_by: agent, the door, revision history), rate-limited, and labeled as agent-reported untrusted data wherever they surface. Review with ctxfile ingest list / rm. Full schema and per-harness prompt snippets: Agent-assisted sessions.

Resources

URI	Returns
context://current	The full ContextObject as JSON.
context://plan	Plan scope only (plan document, metadata).
context://git	Git scope only (branch, status, commits, diff summary).

Resources suit clients that attach context up front; the tool suits models that pull on demand. Same data either way.

Prompts

load-context

Injects the full snapshot into the conversation as a user message, prefixed with the untrusted-data notice. In Claude Code, type “load context” or pick the prompt from the client's prompt list.

ctx-save and ctx-continue

One-tap slash commands on client surfaces that expose MCP prompts: ctx-save instructs the assistant to call save_session with a digest of the current conversation; ctx-continue (optional thread argument) instructs it to call continue_thread and resume from the result.

Scopes on the HTTP door

Over ctxfile serve, each bearer token carries scopes: read:context covers get_context, continue_thread, list_threads, the resources, and load-context; write:sessions covers save_session and ingest_context. A token defaults to both; restrict one to ["read:context"] and every write on that connection is refused with an explanation. Sessions are bound to the token that opened them. Pro tools do not appear on the HTTP surface; the remote surface is exactly the five core tools.

The ContextObject

{
  "meta": {
    "name": "ctxfile", "version": "0.1.0",
    "generatedAt": "2026-07-10T17:41:02Z",
    "root": "...", "tokenBudget": 50000, "tokensUsed": 18432,
    "connectors": [{ "name": "file", "status": "ok", "durationMs": 947 }, ...]
  },
  "plan": "# The Plan ...",             // PLAN.md / TODO.md / docs/plan*.md
  "keyFiles": [{ "path": "src/index.ts", "tokens": 812,
                 "truncated": false, "redactions": 0, "content": "..." }],
  "gitState": { "branch": "main", "staged": [], "modified": [],
                "untracked": [], "ahead": 0, "behind": 0,
                "commits": [...], "diffSummary": "..." },
  "notionPages": [],                    // opt-in connector
  "sessions": [ ... ],                  // Pro session connectors
  "sessionSummary": null                // opt-in local Ollama summary
}

Pro tools

Registered only when a valid license is active, and each group only when its feature is licensed. Without a license the core surface above is all a client sees.

Tool	Feature	What it does
remember	memory	Store a memory entry. Written AES-256-GCM encrypted under `~/.ctxfile/`, key in the OS keychain, provenance recorded on every entry.
recall	memory	Retrieve relevant memory entries for the current work.
forget	memory	Permanently delete a memory entry by id.
consult	consult	Ask every configured provider (Anthropic, OpenAI-compatible, local Ollama) the same question over the live project context; answers stream side by side.
transcribe_voice	voice	Transcribe an audio file with local whisper.cpp, using vocabulary hints built from your repo.

Session digests are not a tool: the Pro session connectors contribute a sessions array to the ContextObject itself. See Connectors and Pro.

Tool count and client caps

Core exposes 5 tools; a fully licensed Pro install exposes 10 over stdio and 5 over HTTP. Comfortably under every client's tool cap (Cursor's is 40), and small enough that schema tokens stay cheap.