MCP integration

Oracus.ai ships a built-in Model Context Protocol server. Any MCP-compatible coding agent — Claude Code, Cursor, Codex CLI, opencode, and others — can mount it and query your Oracus.ai instance directly: cross-repo, cross-source, with citations.

The MCP server is part of the same container you already run. There is no separate install. Once your instance is up, point your agent at it and the tools appear in the agent’s tool list.

For the value-prop overview, see For developers → MCP. This page covers setup and the tool reference.

What the MCP exposes

Six tools, deliberately small and sharp. Each one replaces what an agent would otherwise approximate with many grep + read round-trips.

Tool	When the agent reaches for it	What it returns
`oracus_summarize`	”Brief me on `<repo>` before I read any code”	A compact architectural brief: language hint, what it produces (HTTP routes, RPC, events, packages), what it consumes (internal + external), infrastructure, ownership.
`oracus_locate`	”Where in the codebase is `<concept>` implemented?”	Top hits across every indexed repo, merging three result kinds in one ranking: `[symbol]` (function / method / class with exact file:line), `[source]` (a code file), and `[spec/architectural reference]` (doc/architecture chunk — context only).
`oracus_impact`	”What breaks if I change `<service>`?”	Cross-repo, service-/endpoint-level callers and callees grouped by edge kind (HTTP, RPC, event, shared-db, library), with cautions naming the most likely break vectors.
`oracus_callers`	”Who calls `<symbol>` across the codebase?”	Every call site of a function / method / class — calling symbol, file, line, signature. Cross-repo by construction. Beats grep on CALL SITES specifically (no comment / string false positives).
`oracus_callees`	”What does `<symbol>` call?”	Outgoing edges from a symbol — every callee with file, line, signature. Use to trace a function’s downstream dependencies before refactoring its body.
`oracus_node`	”Read `<symbol>` for me”	The symbol’s full source body (read from the cloned repo on disk), its signature, immediate callers, and immediate callees — one tool call instead of a Read + grep round-trip.

Setup

The MCP server runs over stdio. Mount it in whichever agent you use; the wiring is essentially the same — a command, optional args, optional env. Snippets below assume your Oracus.ai instance is already running and you have a working clone of the server.

A note on transport today. The MCP server currently runs alongside the rest of Oracus.ai — same process, same Postgres. A standalone client that connects to a remote Oracus.ai instance over HTTP is on the near-term roadmap. For now, the configurations below assume the agent and Oracus.ai live on the same machine (or share a working clone path).

Claude Code

Add to ~/.claude.json (global, all projects) or .mcp.json at the project root (per-project):

{
  "mcpServers": {
    "oracus": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["--filter", "@oracus/server", "dev:mcp"],
      "cwd": "/path/to/your/oracus/clone"
    }
  }
}

Restart Claude Code. Run /mcp to confirm oracus is connected and lists six tools: oracus_summarize, oracus_locate, oracus_impact, oracus_callers, oracus_callees, oracus_node.

Cursor

Cursor’s MCP support uses the same stdio shape. Add the same block to your Cursor MCP config (~/.cursor/mcp.json or via the MCP settings panel) and restart.

Codex CLI and other MCP-compatible agents

Any agent that speaks stdio MCP works the same way: launch the Oracus.ai MCP server as a subprocess with stdio transport. The command + args + cwd are identical across hosts.

{
  "command": "pnpm",
  "args": ["--filter", "@oracus/server", "dev:mcp"],
  "cwd": "/path/to/your/oracus/clone"
}

Wrap it in whatever config schema your agent expects.

Environment

The MCP server reads the same .env your Oracus.ai server uses — most importantly DATABASE_URL pointing at your Oracus.ai Postgres. No additional environment variables are required for the MCP server itself; tool calls go through the same retrieval and graph services the rest of Oracus.ai uses.

Verifying it’s wired correctly

After restarting your agent:

List the MCP servers (/mcp in Claude Code, the MCP panel in Cursor). The oracus server should be connected and list six tools.
Ask the agent a question whose answer obviously lives in Oracus.ai’s index — e.g. “Give me an architectural brief on the <one-of-your-repo-slugs> repo.” The agent should call oracus_summarize and return a synthesized brief, not grep your filesystem.
If the tools show up but every call returns “no repo found,” verify your DATABASE_URL points at the same Postgres instance your ingest pipeline has been writing to.

What the agent sees

Every tool returns a single text payload — Markdown formatted, designed for the agent to either quote directly or synthesize into a longer answer. Tool descriptions (the MCP-side guidance that tells the agent when to reach for each tool) are deliberately concrete, with example questions and clear boundaries:

oracus_summarize operates at repo granularity. Sub-services inside a monorepo (e.g. cartservice inside online-boutique) won’t match — the response will say so and suggest oracus_locate as the fallback.
oracus_locate returns results from all indexed repos unless you specify a scope. Cross-repo retrieval is the point. Hits are merged across code symbols and spec/architecture chunks in one ranking — the most relevant hit wins regardless of kind.
oracus_impact covers cross-repo service- and endpoint-level impact. For intra-repo symbol-level impact (who calls this function), use oracus_callers instead.
oracus_callers / oracus_callees / oracus_node are symbol-precise and cross-repo. They scope by repo via the repo argument when symbol names collide; otherwise they return a candidate list to pick from.

Languages and frameworks

Oracus.ai’s internal code-graph extractor reads symbols and edges across 20+ languages:

TypeScript, JavaScript, Python, Go, Rust, Java, C#, Swift, Kotlin, Ruby, C, C++, Objective-C, PHP, Scala, Dart — and more.

Cross-language flows that pure static analysis misses are stitched together in the same pass: Swift ↔ Objective-C bridging, React Native native modules, gRPC service stubs across services.

Web routes are recognized for 17 frameworks — Django, Flask, FastAPI, Express, NestJS, Spring, Rails, Gin, chi, Axum, actix, Rocket, ASP.NET, Vapor, plus React Router, SvelteKit, Vue Router, Nuxt, and Astro. URL patterns link directly to their handler functions, so “where is the /checkout route implemented?” returns the handler, not the routing file.

Roadmap

Near-term additions to the MCP surface:

Standalone client — a thin oracus-mcp binary that connects to a remote Oracus.ai instance over HTTP, so each developer’s agent can talk to a centrally-hosted Oracus.ai without needing a local clone of the server.
Per-team scoping — pass a team argument to scope retrieval to a single team’s repos, mirroring the scope filter already present in the rest of Oracus.ai.
Refactor-precision symbol resolution — SCIP-quality semantic indexing for languages where static name resolution has gaps (dynamic dispatch in JS, reflection in Ruby/Python).

FAQ

Does the MCP server send anything outside our network? No. It reads from your Postgres and writes responses back to the agent over stdio. Nothing crosses your network boundary. The agent may call out to its own LLM provider with the tool output, but Oracus.ai itself never phones home.

Does mounting the MCP slow my agent down? A single Oracus.ai tool call typically takes 100–400 ms (a Postgres query plus an embedding lookup for oracus_locate). One Oracus.ai call routinely replaces ten or more file reads, so net latency is usually lower than the grep-and-read alternative.

Can I use this with my CI bot, my Slack bot, or any other MCP-compatible client? Yes. The MCP server doesn’t care which client connects. As long as the client speaks stdio MCP and can launch the server as a subprocess, the tools work the same way.

What happens if a tool description steers the agent wrong? Tool descriptions are versioned with each Oracus.ai release. If you observe an agent reaching for the wrong tool on a recurring question shape, let us know — descriptions are tunable in a way the underlying tools are not.