MCP Server

MCP server

fai implements the Model Context Protocol (MCP). Any MCP-compatible AI tool can connect to your workbench and read your project context, capture new knowledge, and run workspace intelligence tools.

How to start

The MCP server starts automatically on every fai session. No flags required.

fai                               session server on port 4967, general server on 4966
fai --mcp-session=stdio --auto    session server over stdio, for MCP clients that start fai themselves
fai --share                       HTTP + public relay tunnel (share with remote tools)
fai --preview                     Opens MCP Inspector in your browser - see what your AI sees

fai runs two servers. The session server carries the tools: it reads and writes this session's context. The general server (fai-g in your agent configs) serves fai's workflow prompts, docs, and skills, and needs no session. fai starts both. To run the general server alone, use fai serve.

For stdio, use --mcp-session=stdio, not --mcp=stdio. --mcp sets the general server's port, so fai --mcp=stdio gives your client no session tools and waits on the session picker.

To target a specific session, pass fai --sessionId=<id>. If the target session was previously archived, it is automatically unarchived.

fai --share opens a 4-tier public relay: tunnel.fathym.com → localtunnel.me → cloudflared → localhost.run SSH. If all tiers fail, fai still runs locally.

Note: --mcp-session=stdio and --share cannot be combined.

Preview mode

fai --preview

Opens MCP Inspector pointed at your running fai MCP server. The inspector shows every tool your AI can call, every vault entry it reads, and the full project context fai has built from your sessions. You can browse entries, call tools yourself, and verify exactly what your AI sees.

The inspector process is managed by fai — it starts automatically and shuts down when your session ends.

Standalone preview

Preview any installed or ad-hoc MCP server outside of a fai session:

fai mcp preview                                  # interactive selector
fai mcp preview github                           # named server
fai mcp preview --host http://localhost:3000/mcp  # ad-hoc URL

See Commands → fai mcp preview for full reference.

Tools

Session tools

Tool	What it does
fai_session_capture	Write one capture entry to the current session
fai_session_capture_batch	Write multiple captures in one call
fai_session_petname	Register a vocabulary term for the current project or personally
fai_agents_list	List detected local coding agents

Workspace tools

Tool	What it does
fai_workspace_list	List files by glob pattern
fai_workspace_read	Read file content with line pagination
fai_workspace_search	Search file contents by regex or literal query
fai_workspace_diff	Git diff across workspace repos
fai_workspace_status	Git status across workspace repos

AI agent tools

Tool	What it does
fai_agent_consult	Ask a local agent a question about the workspace
fai_agent_plan	Generate a structured implementation plan
fai_agent_propose	Generate a code change proposal (unified diffs)
fai_agent_apply	Apply an approved proposal
fai_agent_run	Run an autonomous coding agent task
fai_agent_result	Check the status of a background fai_agent job

Docs

Tool	What it does
fai_read_doc	Read a @fathym/steward or @fathym/fai doc by URI

Run fai --preview to open MCP Inspector and see all active tools with their schemas.

Resources

Your workbench state is exposed as MCP resources:

• FAI-SESSION.md — current session context
• FAI-PROJECT.md — project-level accumulated knowledge
• FAI-PERSONAL.md — personal preferences across all projects
• Petnames — workbench and personal vocabulary registries
• Steward docs — @fathym/steward framework reference (requires FAI_STEWARD_DOCS_PATH env)
• fai docs — vault architecture, custom vault/workbench/mode guides

Prompts

Six core prompts guide session workflow:

• orient — orient yourself for a fai session; read all FAI context files
• capture/guide — learn how to contribute back to fai (capture structure, batching)
• workspace/guide — workspace intelligence tools and escalation workflow
• fai/workspace — quick reference for file tools (list, read, search, diff, status)
• fai/agents — quick reference for local AI agent tools
• fai/edit-session — frame a coding session for AI-assisted code editing

Six holonic development prompts for building fai extensions:

• holonic/create-capability / holonic/create-agent / holonic/create-workflow
• holonic/audit / holonic/explain / holonic/compose-steward

Connecting Claude Code

Add to Claude Code's MCP config (~/.claude.json, or .mcp.json in your project):

{
  "mcpServers": {
    "fai": {
      "command": "fai",
      "args": ["--mcp-session=stdio", "--auto"]
    }
  }
}

When Claude Code starts this MCP server, --auto joins the most recently started session on this machine without prompting - which can be a session from another project. To pin this project's session, add "--sessionId=<id>" to the args array.

fai also writes CLAUDE.md directly when you run fai orient — Claude Code reads your full workbench context on every session start.

Connecting Cursor

fai writes .cursor/rules/fai-context.mdc with your current project context. Cursor reads this automatically. For live MCP connection, add to Cursor's MCP settings with command fai and args ["--mcp-session=stdio", "--auto"].

Connecting Windsurf

fai writes .windsurf/rules/fai-context.md with your current project context. For live MCP, configure Windsurf's MCP settings with command fai and args ["--mcp-session=stdio", "--auto"].

Auto-configuration

When you run fai, it automatically writes MCP server configuration into each detected agent's native config file — no manual steps needed:

Agent	Config path (all user-level global)	Transport
Claude Code	~/.claude.json	http
Cursor	~/.cursor/mcp.json	http
Cline	VS Code user data: …/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json	http
Copilot (VS Code)	VS Code user data: …/Code/User/mcp.json	http
Windsurf	~/.codeium/windsurf/mcp_config.json	http
Codex CLI	~/.codex/config.toml	http
Gemini CLI	~/.gemini/settings.json	http
JetBrains AI	~/.junie/mcp/mcp.json	http
Goose	~/.config/goose/config.yaml	http
Antigravity	~/.gemini/antigravity/mcp_config.json	http
Continue	~/.continue/config.json	http

VS Code user data lives at ~/Library/Application Support/Code/User/ on macOS, ~/.config/Code/User/ on Linux, and %APPDATA%\Code\User\ on Windows.

fai works with 16 agents. 15 of them (all but OpenClaw) receive context injection into their native rules files on every session start. The 11 listed here also get MCP server configuration written to user-level global paths, all using type: 'http'.

The manual configuration examples above are for reference or to override defaults.

Installing third-party MCP servers

Use fai mcp install to add any MCP server to all your agents at once:

fai mcp install https://mcp.example.com/api --name example --auth sk-token

This writes the server entry (with auth) into every detected agent's config — Claude, Cursor, Cline, Copilot, and the rest. No manual editing needed.

Add --task to auto-start a local MCP server on each fai session:

fai mcp install http://localhost:3000/mcp --name github --task "npx @mcp/server-github"

See Commands → fai mcp install for full reference.

Skill files

fai mcp generate generates a .md skill file per MCP prompt:

fai mcp generate                        # writes to .claude/commands/ in CWD
fai mcp generate --output /path/to/dir  # custom output directory

Each prompt maps to a file by path — capture/guide → .claude/commands/capture/guide.md, holonic/explain → .claude/commands/holonic/explain.md. Claude Code reads .claude/commands/ as slash commands.

fai generates skill files automatically on each session start for Claude Code.

Sharing your workbench

fai --share

Opens a public tunnel so remote AI tools (claude.ai, hosted Cursor, etc.) can connect. Your workbench URL is printed on startup. Context captured by remote tools flows back into your vault.

Governance & security

fai applies a 6-layer governance chain to every MCP tool call — tool exposure control, rate limiting, API key auth, scope enforcement, audit logging, and secret redaction from results. All layers are active with no configuration required for local use.

See Governance & Security for configuration and details.