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 — no separate service to deploy. Your developers need nothing installed at all: you mint them a token, they paste a URL into their agent config, and the tools appear in their 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

Your running instance serves MCP over HTTP at POST /mcp, on the same host and port as the rest of Oracus.ai. Every developer points at that one URL with their own token.

1. Mint a token (admin, once per developer)

From the API, using your ADMIN_TOKEN or an admin session:

curl -X POST https://oracus.your-org.internal/api/admin/mcp-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name": "ana - laptop"}'

The response carries the token once:

{
  "id": "…",
  "name": "ana - laptop",
  "prefix": "orc_mcp_a1b2c3d4",
  "token": "orc_mcp_a1b2c3d4…",
  "createdAt": "2026-08-16T14:46:54.227Z"
}

Only a SHA-256 of the token is stored, so it cannot be recovered later — if it’s lost, revoke the key and mint a new one. prefix is kept in the clear so you can identify a key in a list without it being usable.

Add "expiresAt": "2027-01-01T00:00:00Z" to the request body for a key that expires on its own.

2. Point the agent at it (each developer)

Claude Code — add to ~/.claude.json (global) or .mcp.json at the project root:

{
  "mcpServers": {
    "oracus": {
      "type": "http",
      "url": "https://oracus.your-org.internal/mcp",
      "headers": { "Authorization": "Bearer orc_mcp_a1b2c3d4…" }
    }
  }
}

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, Codex CLI, and others — any client that speaks streamable-HTTP MCP takes the same three things: the URL, the Authorization header, and a name. Wrap them in whatever config schema your agent expects.

Managing keys

# List keys — names, prefixes, last use, revocation state. Never token material.
curl https://oracus.your-org.internal/api/admin/mcp-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Revoke. Takes effect on the developer's next tool call.
curl -X DELETE https://oracus.your-org.internal/api/admin/mcp-keys/<id> \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Revocation is a soft delete: the row stays for the audit trail and stops resolving. lastUsedAt is recorded on use (coalesced to at most one write per five minutes), so you can spot keys that have gone idle.

Local stdio (alternative)

If the agent runs on the same machine as Oracus.ai — or you’re developing Oracus.ai itself — you can skip HTTP and launch the server as a subprocess over stdio. This needs a working clone and an .env whose DATABASE_URL reaches your Oracus.ai Postgres directly.

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

Prefer the HTTP endpoint for anyone who isn’t hacking on Oracus.ai itself — it needs no clone and, more importantly, no database credentials on a developer laptop.

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,” the connection is fine and the index is the problem — check that your ingest pipeline has run against the instance you’re pointed at.

To test the endpoint without an agent in the loop:

curl -X POST https://oracus.your-org.internal/mcp \
  -H "Authorization: Bearer orc_mcp_a1b2c3d4…" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A healthy instance returns the six tool definitions. A 401 with "Invalid or revoked MCP token." means the token is unknown, revoked, or expired — the endpoint deliberately doesn’t distinguish which.

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:

Per-key scoping — bind a key to a team or a repo set so a developer’s agent sees only what that team can see. Today every valid key reaches the whole index, matching the org-wide read model of the rest of Oracus.ai.
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.
Ticket and test tools — the MCP surface is code-graph shaped today. Bringing Jira/Linear tickets and test results into it would let an agent ask “what’s the ticket history behind this module” without leaving the tool loop.
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. Traffic goes from the developer’s machine to your Oracus.ai instance and no further — if that instance is internal-only, so is the MCP endpoint. The agent may call out to its own LLM provider with the tool output, but Oracus.ai itself never phones home.

Do developers need database access? No — that’s the point of the HTTP endpoint. They hold a scoped token that reaches POST /mcp and nothing else. Only the Oracus.ai server talks to Postgres. (The stdio alternative does require DB reach, which is why it’s for people working on Oracus.ai itself.)

What happens if a developer’s token leaks? Revoke it (DELETE /api/admin/mcp-keys/<id>) and mint a replacement; the old one stops working on its next call. A leaked token grants read access to your index — the same reads that developer could already perform in the Oracus.ai UI — and nothing else. It cannot write, ingest, or change configuration.

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 — mint it a key of its own so you can revoke it independently of any person’s.

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.