@jerenpm/omni-mcp

MCP server that exposes Omni's shared project memory to any MCP-compatible AI coding agent (Claude Code, Codex CLI, OpenCode, etc.). Phase 1 of the provider-free migration plan.

The server runs locally over stdio, authenticates against an Omni server using the user's existing session token, and exposes a small set of tools:

• omni_memory_search — ranked retrieval over project memory
• omni_memory_global_search — project-wide durable memory
• omni_teammate_context — retrieval scoped to a single teammate
• omni_memory_write — persist a memory entry
• omni_project_list — list projects the user belongs to
• omni_project_bootstrap — snapshot of the active project
• omni_team_pulse — per-teammate activity buckets

Install

From the repo root:

cd apps/mcp
npm install
npm run build

This produces dist/index.js and exposes the omni-mcp binary. Until the package is published, point your MCP client at the absolute path to that file (or run npm link from apps/mcp).

Configure

omni-mcp reads configuration in this order:

1. Environment variables.
2. ~/.omni/credentials.json (created later by the omni login CLI from Phase 2).

For now, create the credentials file manually:

{
  "api_base_url": "http://localhost:8000",
  "session_token": "<bearer token issued by /auth/desktop/exchange>",
  "project_id": "<optional default project uuid>",
  "user_id": "<your agent uuid within the project>"
}

session_token is the token the Omni desktop app stores after Google sign-in. user_id is required only if you intend to use omni_memory_write (every memory entry needs an author agent id).

You can also override any of these per-run:

| Variable | Effect | | -------------------- | ------------------------------------------------ | | OMNI_API_BASE_URL | Override the API URL | | OMNI_SESSION_TOKEN | Override the bearer token | | OMNI_PROJECT_ID | Default project id sent as X-Project-Id | | OMNI_USER_ID | Author agent id used by omni_memory_write | | OMNI_MCP_TIMING | Set to 1 to emit structured latency logs to stderr |

Register with Claude Code

Add the server to your Claude Code MCP config (~/.claude.json, or a project-scoped .mcp.json):

{
  "mcpServers": {
    "omni": {
      "command": "node",
      "args": ["/absolute/path/to/Omni/apps/mcp/dist/index.js"],
      "env": {
        "OMNI_API_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Restart Claude Code. The omni_* tools should appear in the tool list.

Register with Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.omni]
command = "node"
args = ["/absolute/path/to/Omni/apps/mcp/dist/index.js"]

[mcp_servers.omni.env]
OMNI_API_BASE_URL = "http://localhost:8000"
OMNI_SESSION_TOKEN = "<bearer token issued by /auth/desktop/exchange>"
OMNI_PROJECT_ID = "<default project uuid>"
OMNI_USER_ID = "<your agent uuid within the project>"

omni init --agent codex and omni run manage this entry automatically. Restart Codex CLI sessions to pick up manual changes.

Develop

npm run dev        # tsc --watch
npm run typecheck
npm start          # run compiled server over stdio (manual smoke test)

omni-mcp writes diagnostic lines to stderr on startup. The Omni server must be running and reachable at OMNI_API_BASE_URL for any tool call to succeed.

For CLI latency investigations, launch the agent with OMNI_MCP_TIMING=1. The MCP server emits JSON lines to stderr for each tool call and underlying Omni API request. Analyze a captured log with:

npm run analyze:timing -- /path/to/omni-mcp-stderr.log

Known limits (Phase 1)

• Tool calls fail with OMNI_USER_ID is not configured if you try to write memory without supplying an author agent id. The Phase 2 CLI will populate this automatically.
• No HTTP transport yet — stdio only. HTTP transport is planned for the VS Code extension in Phase 5.
• Tasks are not yet exposed; task routes need to land on the server first.
• Project switching at runtime requires re-launching the server with a different OMNI_PROJECT_ID.