Index your codebase and query it with Claude

By the end of this recipe, you can ask questions like "what functions call validateCard?" or "which files import the billing module?" directly from Claude Code — and get grounded, cited answers backed by your actual codebase graph.

Oxagen ingests your repository into a typed knowledge graph: files, functions, classes, imports, and call edges. The ontology.ask MCP tool lets any Claude agent query that graph in natural language. No embeddings to manage, no prompt-stuffing entire files into context.

Time: ~15 minutes
Difficulty: Beginner
Code: github.com/oxagenai/oxagen-cookbook

What you'll build

A configured workspace where Claude Code can answer structural questions about your codebase:

> ontology.ask: "What functions modify the user object?"

processPayment() modifies user.balance [node:a3f2...] after calling
validateCard() [node:b8c1...]. updateProfile() writes user.name and
user.email [node:c4d9...].

Candidates considered: 24 | Retrieval: hybrid

Each answer cites specific nodes by UUID — auditable, deterministic, grounded in your graph.

Prerequisites

• An Oxagen account (oxagen.ai)
• A GitHub repository (public, or private with the Oxagen GitHub App installed)
• Claude Code with MCP support (v1.0+)
• An Oxagen API key (Settings → API Keys in the dashboard)

Step 1: Connect your repo

Open the Oxagen dashboard and navigate to your workspace. Click Connections in the left sidebar, then Add connection → GitHub.

If your repo is public, paste the full repository URL (e.g. https://github.com/your-org/your-repo) and click Connect.

For private repos, click Install GitHub App first. This grants Oxagen read-only access to the repositories you select — no write permissions are requested.

Once connected, ingestion starts automatically. Oxagen runs a 5-phase pipeline:

1. Fetch — clones the repo at HEAD
2. Discover — enumerates source files in the languages enabled on the connection (TypeScript / JavaScript and Python; configured via the languages setting on the GitHub connection — see Code Graph)
3. Parse — extracts functions, classes, interfaces, imports, and call sites via tree-sitter
4. Resolve — wires cross-file call references to their destination nodes
5. Write — persists typed nodes and edges into the workspace graph

Each file produces a code.file node, each function a code.function node, and so on. Edges carry semantic types: defines, calls, imports, extends.

Step 2: Wait for ingestion

The connection card shows a progress indicator. For a 1,000-file TypeScript monorepo, expect 3–8 minutes depending on parse complexity. A 10,000-file repo takes 15–25 minutes.

When ingestion completes, the connection status changes to Active and the graph view in your workspace populates with nodes. You can explore it visually — click any node to inspect its properties and edges.

If ingestion fails, check the connection card for the error detail. Common causes: the GitHub App lacks access to the repo, or the repo contains no supported file types.

Step 3: Configure MCP in Claude Code

Add Oxagen to your Claude Code MCP configuration. Create or edit .mcp.json in your project root:

{
  "oxagen": {
    "command": "npx",
    "args": ["-y", "@oxagen/mcp-server"],
    "env": {
      "OXAGEN_API_KEY": "your_api_key_here"
    }
  }
}

Replace your_api_key_here with the key from Settings → API Keys.

Restart Claude Code. You should see Oxagen tools available — verify with /mcp in the Claude Code REPL.

Step 4: Query your codebase

With MCP configured, Claude Code can use ontology.ask to query your graph. Here are three example queries with realistic outputs:

Find call relationships:

ontology.ask: "What functions call validateCard?"

processPayment() [node:a3f2c1d8] calls validateCard() directly.
chargeSubscription() [node:b7e9f2a1] calls it via the payment pipeline
after checking account balance [node:c4d9e3b2].

Candidates considered: 31 | Retrieval: hybrid

Understand module dependencies:

ontology.ask: "Which files import the auth module?"

services/api/routes/users.ts [node:d1f8a2c3] and
services/api/routes/billing.ts [node:e5b7c9d4] both import from
auth/middleware.ts [node:f2a8b3c1]. The middleware exports
requireAuth and getSession.

Candidates considered: 18 | Retrieval: hybrid

Locate error handling:

ontology.ask: "Where are PaymentError exceptions thrown?"

PaymentError is thrown in processPayment() [node:a3f2c1d8] when
card validation fails, and in chargeSubscription() [node:b7e9f2a1]
when the Stripe API returns a decline code.

Candidates considered: 12 | Retrieval: hybrid

Each citation [node:uuid] links to a specific node in your workspace graph — you can inspect it in the dashboard.

Step 5: Query via API

The same queries work directly against the REST API — useful for CI scripts, pre-commit hooks, or custom tooling:

export OXAGEN_API_KEY=your_api_key_here

curl -X POST https://api.oxagen.ai/v1/ontology/prompt \
  -H "Authorization: Bearer $OXAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What functions call validateCard?",
    "force_intent": "query"
  }'

Response:

{
  "intent": "query",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "answer": {
    "narrative": "processPayment() calls validateCard() directly...",
    "citations": [
      {
        "node_id": "a3f2c1d8-...",
        "type": "code.function",
        "name": "processPayment",
        "excerpt": "processPayment"
      }
    ],
    "candidate_count": 31,
    "retrieval_mode": "hybrid"
  }
}

The correlation_id is echoed in the X-Correlation-Id response header — use it to trace a query through your logs.

What's next

• Agent memory — attach persistent memory to your workspace so agents accumulate knowledge across sessions. Read the docs.
• MCP tool reference — full list of 30+ tools available via the MCP server. Read the docs.
• More recipes — github.com/oxagenai/oxagen-cookbook

Get started free · MCP server docs