Empirical Docs / MCP

MCP server.

Empirical exposes 12 MCP tools over local stdio and a remote HTTP /mcp endpoint. All tools require OAuth bearer token auth.

Transport modes

Claude Code, Codex, and Copilot are set up by `empirical install`, which configures local stdio MCP and reads credentials from the CLI token store. Cursor and Windsurf have no CLI installer; connect them with a manual remote MCP config pointed at the hosted HTTP endpoint below. ChatGPT and other remote integrations also use the hosted endpoint.

# Remote HTTP endpoint
https://empirical.gauzza.com/mcp

# Authorization header required
Authorization: Bearer <access_token>

Local stdio: Stdio mode is configured automatically by empirical install for supported clients (Claude Code, Codex, Copilot). Cursor and Windsurf require manual MCP config; see their docs pages.

Write tools

Create and modify memory graph nodes.

  • record_graph_memory — create or merge a memory from conversation context. Accepts category, summary, mass, tags, auto-link, and dedupe flags. The primary write tool for agents.

Read & query tools

Retrieve memories by ID, semantic search, list, or graph traversal.

  • query_memories — semantic search with optional filters: category, tags, date range, month bucket, geolocation radius, topK. Supports richer result context.
  • get_memory — retrieve a single memory by ID with full metadata, data payload, and version history.
  • list_memories — list memories with optional category/tag filters. Useful for deterministic browsing before a follow-up action.

By-query convenience tools

These tools resolve the target memory by semantic fuzzy search instead of requiring an explicit memory ID — useful when agents don't know the ID upfront.

  • add_note_by_query — fuzzy-find a memory by natural language, then append a note.
  • update_memory_by_query — fuzzy-find a memory by natural language, then apply a patch.
  • delete_memory_by_query — fuzzy-find a memory by natural language, then delete it (requires confirm=true).

Utility tools

Session, workspace, and self-discovery helpers.

  • get_empirical_policy — return the memory-use policy for the current client.
  • get_user — return the authenticated Empirical user profile and account metadata.
  • list_workspaces — list all workspaces available to the current OAuth client.
  • get_current_workspace — get the active workspace for this client session.
  • set_current_workspace — switch active workspace to scope memory recall to a specific project or context.

Last updated: June 26, 2026