Reference

MCP tools

OpenEZ exposes 10 tools over MCP, all backed by the same local SQLite index. This page says what each one does, when an agent should reach for it, and what it accepts.

Connect an agent

One command writes the agent's config, registers the project, and indexes it. The agent then starts openez serve --mcp over stdio and sees the tools below.

openez setup codex .

Workspace scope

Read tools (code_query, code_context, graph_neighbors, diff_context, memory_recall) take workspaceIds or paths for several workspaces, or workspaceId / path for one.
Single-workspace tools (code_outline, memory_write, index_workspace, remove_workspace) take one workspaceId or path.
With no scope, OpenEZ reads .openez/workspace.json from the current project or a parent folder. Failing that it uses the workspace registered at that path, then the only registered workspace; with several it returns an error asking for workspaceId or path. remove_workspace is the exception: it always needs an explicit one.
maxTokens bounds the whole serialized response; across several workspaces the budget is split between them.

Retrieval

Find and understand code without reading whole files.

code_query

one or many workspaces

Ranked code and documentation chunks for a question or a few keywords. Full-text search with graph expansion (and optional embedding reranking), returned inside a token budget.

Call it when you need to find where something lives or how it works, before opening any file.

Parameters of code_query
Parameter	Type	Description
query*	string	Question or keywords to search for.
limit	integer	Maximum number of results, up to 100.
maxTokens	number	Token budget for the whole response across all selected workspaces, 32 to 100,000 (default 4,000).

code_outline

one workspace

The AST outline of one file: functions, classes, and exported symbols with line numbers.

Call it when you only need a file's structure. It costs a fraction of reading the file (about 50 tokens against 3,000 in the tool's own description).

Parameters of code_outline
Parameter	Type	Description
path*	string	Relative or absolute path to the file inside the workspace.

code_context

one or many workspaces

Graph-adjacent context for a symbol or a file: the code that calls it, imports it, or sits next to it in the graph.

Call it when you are about to change a symbol or file and need to know what depends on it.

Parameters of code_context
Parameter	Type	Description
symbolOrPath*	string	A symbol name or a file path.
hops	integer	How far to follow the graph, 1 to 5.
limit	integer	Maximum records per workspace (default 50, up to 200).
maxTokens	number	Token budget for the whole serialized response, 32 to 100,000.

graph_neighbors

one or many workspaces

The raw graph nodes and edges around a label or a node id, with their relationship types such as imports, calls, and defines.

Call it when you want to inspect relationships directly instead of reading ranked text.

Parameters of graph_neighbors
Parameter	Type	Description
nodeId	string	Start from this node id…
label	string	…or from the node with this label.
edgeTypes	string[]	Only follow these edge types.
depth	integer	Traversal depth, 1 to 5.
limit	integer	Maximum nodes and edges per workspace, up to 200.
maxTokens	number	Token budget for the whole serialized response, 32 to 100,000.

diff_context

one or many workspaces

Analyzes a git diff and returns the affected AST symbols with their callers and callees. By default it covers tracked staged and unstaged changes; untracked files are not included.

Call it when you are reviewing a change and want to know what it touches.

Parameters of diff_context
Parameter	Type	Description
ref	string	Git ref or commit range, for example HEAD~1, main, or origin/main.
staged	boolean	Analyze only staged changes.
limit	integer	Maximum callers per symbol, up to 50 (default 5).
maxTokens	number	Token budget, 32 to 100,000. The formatted summary is dropped before structured symbols and files.

Memory

Decisions that outlive a single session.

memory_recall

one or many workspaces

Active technical decisions and learned memories stored for the project.

Call it when you start work in a new session. Query with one to three keywords from the task.

Parameters of memory_recall
Parameter	Type	Description
query*	string	One to three task keywords.
limit	integer	Maximum number of memories, up to 100.
maxTokens	number	Token budget for the whole serialized response, 32 to 100,000.

memory_write

one workspace

Persists a technical decision or a learned constraint so later sessions can recall it.

Call it when an architectural decision or a non-obvious constraint has been confirmed.

Parameters of memory_write
Parameter	Type	Description
title*	string	Short title.
content*	string	The decision or constraint.
tags	string[]	Tags to recall it by.
supersedesId	string	Id of an earlier memory this one replaces.

Workspaces

See, refresh, and remove what is indexed.

list_workspaces

no workspace needed

The registered workspaces and their current status.

Call it when you need a workspace id or path to scope another call.

index_workspace

one workspace

Runs indexing for a workspace. The MCP runtime already registers and indexes a project and keeps it current as files change; use this to refresh or rebuild on demand.

Call it when an index looks stale or you want a full rebuild.

Parameters of index_workspace
Parameter	Type	Description
mode	incremental \| full	Incremental updates changed files; full rebuilds the index.

remove_workspace

destructiveone workspace

Removes a workspace from the registry and deletes its .openez data directory. This is destructive and cannot be undone.

Call it when the user has explicitly approved it. Never call it on your own initiative.

Parameters of remove_workspace
Parameter	Type	Description
confirm*	boolean	Must be true. Without it the call returns an error and removes nothing.
workspaceId or path*	string	Pass exactly one. It never falls back to the current project.

Example: `code_query`

A real call against this repository, abbreviated. Four of the twenty candidate files were selected: they are 24,620 tokens in full, and the response is 1,120.

Request

{
  "query": "where is the workspace registry created and how are workspaces resolved",
  "path": "/abs/path/to/project",
  "limit": 4,
  "maxTokens": 1200
}

Response

{
  "answerContext": "[source: apps/mcp/src/mcp-core.ts:186-215 | score: 0.020]\n  async function resolveDefaultWorkspace(): Promise<WorkspaceLike> { … }\n\n[source: packages/db/src/sqlite/registry-db.ts:32-116 | score: 0.020]\n  export function migrateRegistrySchema(sqlite: SqliteLike): void { … }",
  "sources": [
    {
      "path": "apps/mcp/src/mcp-core.ts",
      "startLine": 186,
      "endLine": 215,
      "score": 0.0205,
      "reason": "retrieved-context",
      "workspaceId": "openez"
    }
  ],
  "metrics": {
    "candidateFiles": 20,
    "selectedFiles": 4,
    "selectedFullFileTokens": 24620,
    "tokenBudget": 1200,
    "truncated": true,
    "responseTokens": 1120
  }
}

The tools are defined in apps/mcp/src/mcp-core.ts. Back to the overview

Connect an agent

Workspace scope

Retrieval

Memory

Workspaces

Example: code_query

Example: `code_query`