MCP Server

The SessionFS MCP server gives AI coding agents access to your session history and project knowledge base during conversations. Agents can search past sessions, read project context, and contribute knowledge back — building a shared memory that persists across tools and teammates.

Transports: stdio for local use (agent launches sfs mcp serve as a subprocess) and HTTP/SSE for remote use (cloud-hosted agents like claude.ai).

Installation

Run sfs mcp install --for <tool> to register the MCP server with your AI tool. This registers the server in the tool’s MCP configuration and injects knowledge-contribution instructions into the tool’s project config file (e.g., CLAUDE.md, .cursorrules).

Supported tools:

sfs mcp install --for claude-code   # ~/.claude.json
sfs mcp install --for cursor        # ~/.cursor/mcp.json
sfs mcp install --for codex         # via codex mcp add
sfs mcp install --for gemini        # via gemini mcp add
sfs mcp install --for copilot       # ~/.copilot/config.json
sfs mcp install --for amp           # ~/.amp/config.json
sfs mcp install --for cline         # VS Code globalStorage
sfs mcp install --for roo-code      # VS Code globalStorage

To skip the instruction injection (server registration only):

sfs mcp install --for claude-code --skip-instructions

Tools

The MCP server exposes 22 tools in four categories.

Session Tools

search_sessions

Search past AI coding sessions by keyword, error message, or file path.

Parameter	Type	Required	Description
query	string	yes	Keywords, error messages, or file paths to search for
tool_filter	string	no	Filter by source tool (claude-code, codex, gemini, cursor, copilot, amp, cline, roo-code)
max_results	number	no	Maximum results to return (default: 5)

get_session_context

Retrieve the full conversation from a specific session. Use after search_sessions finds a relevant hit.

Parameter	Type	Required	Description
session_id	string	yes	Session ID in ses_... format
max_messages	number	no	Limit messages returned (default: 50)
summary_only	boolean	no	Return metadata only, no messages (default: false)

list_recent_sessions

List recent sessions with optional filtering.

Parameter	Type	Required	Description
limit	number	no	Max sessions to return (default: 10)
tool_filter	string	no	Filter by source tool
project_filter	string	no	Filter by project/workspace path substring

find_related_sessions

Find sessions that touched a specific file or encountered a similar error. Provide file_path or error_text (at least one).

Parameter	Type	Required	Description
file_path	string	no	Find sessions that modified this file
error_text	string	no	Find sessions with similar errors
limit	number	no	Max results (default: 5)

get_session_summary

Get a structured summary — files modified, commands run, tests executed, errors encountered, packages installed.

Parameter	Type	Required	Description
session_id	string	yes	Session ID in ses_... format

get_audit_report

Get the LLM Judge trust audit — verifiable claims, verdicts (verified/unverified/hallucination), confidence scores, CWE mappings.

Parameter	Type	Required	Description
session_id	string	yes	Session ID in ses_... format

get_session_provenance

Return the instruction provenance recorded for a session — what rules and artifacts shaped the agent at capture time. Returns rules_version, rules_hash, rules_source (sessionfs / manual / mixed / none), and the instruction_artifacts list.

Parameter	Type	Required	Description
session_id	string	yes	Session ID in ses_... format

Knowledge Read

get_project_context

Get the shared project context document — architecture decisions, conventions, wiki pages, and recent knowledge entries. Call early in a session to understand the project. Use get_context_section or get_wiki_page instead when you only need one slice — they return less and cost less.

Parameter	Type	Required	Description
git_remote	string	no	Git remote URL (auto-detected from working directory if omitted)

get_context_section

Return one section of the project context document by slug instead of the full document. If the slug is not found, the response lists the available slugs so you can retry.

Parameter	Type	Required	Description
slug	string	yes	Section slug (lowercase, non-alphanumeric collapsed to _)
git_remote	string	no	Git remote URL (auto-detected if omitted)

get_wiki_page

Read one wiki page’s full content plus backlinks. Cheaper than get_project_context when you already know the page slug.

Parameter	Type	Required	Description
slug	string	yes	Wiki page slug (e.g., architecture)
git_remote	string	no	Git remote URL (auto-detected if omitted)

search_project_knowledge

Search across knowledge entries and wiki pages by keyword. Use this when you have a query string. Use list_knowledge_entries instead when you want a filtered list with no query.

Parameter	Type	Required	Description
query	string	yes	What to search for
entry_type	string	no	Filter by type: decision, pattern, discovery, convention, bug, dependency
limit	number	no	Maximum results (default: 10)

list_knowledge_entries

Filtered list of knowledge entries with pagination. Useful when you want to browse by type, claim class, freshness, or origin session without a search query.

Parameter	Type	Required	Description
entry_type	string	no	One of decision, pattern, discovery, convention, bug, dependency
claim_class	string	no	evidence, claim, or note
freshness_class	string	no	current, aging, stale, or superseded
dismissed	boolean	no	Include dismissed entries (default: false)
session_id	string	no	Only entries linked to this session
sort	string	no	created_at_desc (default), last_relevant_at_desc, confidence_desc
page	number	no	1-based page number (default: 1)
limit	number	no	Page size, max 200 (default: 50)

get_knowledge_entry

Return one knowledge entry’s full record, including last_relevant_at for stale review.

Parameter	Type	Required	Description
id	number	yes	Knowledge entry ID

get_knowledge_health

One call for the dashboard banner data — pending, compiled, dismissed, and total counts; stale and low-confidence counts; word count for the compiled context; recommended next actions.

No parameters required.

ask_project

Ask a question about the project. Gathers project context, searches the knowledge base, and finds related local sessions to assemble research material.

Parameter	Type	Required	Description
question	string	yes	A question about the project

Knowledge Write

add_knowledge

Add a knowledge entry to the project knowledge base. Use when you discover patterns, decisions, conventions, bugs, or dependencies.

Parameter	Type	Required	Description
content	string	yes	The knowledge entry text
entry_type	string	yes	One of: decision, pattern, discovery, convention, bug, dependency
session_id	string	no	Link this entry to a specific session
confidence	number	no	Confidence score 0.0—1.0 (default: 1.0)

update_wiki_page

Create or update a wiki page in the project knowledge base. Use for longer-form documentation of architecture, conventions, or concepts.

Parameter	Type	Required	Description
slug	string	yes	URL-safe page identifier (e.g., architecture)
content	string	yes	Full page content in markdown
title	string	no	Page title (derived from slug if omitted)

list_wiki_pages

List all wiki pages for the project. Returns page slugs, titles, word counts, and entry counts. No parameters required.

compile_knowledge_base

Trigger a compile pass on the project’s knowledge base. Promotes pending entries, refreshes section pages and concept pages, and rebuilds the compiled context document. Returns a structured result: entries_compiled, context_words_before, context_words_after, section_pages_updated, concept_pages_updated, compiled_at.

No parameters required.

dismiss_knowledge_entry

Dismiss a knowledge entry that is stale, wrong, or no longer relevant. Idempotent — calling twice is a safe no-op. Writes a full audit triple (dismissed_at, dismissed_by, dismissed_reason) and the underlying PUT /entries/{id} is row-locked with SELECT FOR UPDATE so concurrent dismissals can’t tear the audit record.

Parameter	Type	Required	Description
id	number	yes	Knowledge entry ID
reason	string	yes	Short justification (e.g., "superseded by entry 412" or "wrong file path")

Rules (Read-only)

get_rules

Returns the canonical project rules record plus compilation config for the current repo (static preferences, enabled tools, knowledge / context injection settings, tool overrides). Agents cannot modify rules through MCP — changes must go through sfs rules edit or the dashboard.

Parameter	Type	Required	Description
git_remote	string	no	Override auto-detected git remote

get_compiled_rules

Returns the compiled rule text for a requested tool, or for the current tool if safely inferable. Useful when an agent needs to understand what behavior contract was materialized for its tool.

Parameter	Type	Required	Description
tool	string	no	Tool slug: claude-code, codex, cursor, copilot, gemini
git_remote	string	no	Override auto-detected git remote

Agent Knowledge Contribution

When sfs mcp install runs, it injects a MANDATORY instructions block into the tool’s project config file (e.g., CLAUDE.md, .cursorrules). These instructions tell the agent it must call add_knowledge() when discovering architecture decisions, code patterns, bugs, dependencies, or conventions — and must not end a session without contributing if it learned something new.

This creates a knowledge loop: each session reads project context at the start and writes back discoveries at the end. Tools that support project-level instructions: Claude Code (CLAUDE.md), Codex (codex.md), Gemini (GEMINI.md), Cursor (.cursorrules). For other tools, instructions are served at runtime via get_project_context.

Remote MCP (HTTP/SSE)

For cloud-hosted agents (e.g., claude.ai) that cannot launch local processes, SessionFS supports HTTP/SSE transport with OAuth authentication. The remote server is deployed alongside the SessionFS API — agents connect via the SSE endpoint and authenticate using the same API key from sfs auth login. No separate service required.

Configuration

Variable	Description
SFS_API_URL	SessionFS cloud API URL (for knowledge tools)
SFS_API_KEY	API key for cloud authentication

sfs mcp serve

Runs the MCP server on stdio transport. Connect from any MCP-compatible client.

Rebuild the search index:

sfs mcp index

Re-indexes all local sessions into the full-text search database.

Uninstall:

sfs mcp uninstall --for claude-code

Removes the MCP server registration and cleans up injected knowledge instructions from the project config file. Supported tools are the same as for install.