Oracle Discovery API

Overview

The Oracle normally runs the LLM relationship inwards: its own model (Ollama) calls C3 tools to analyze your projects. The Discovery API flips that — it exposes those same capabilities outwards, so an external LLM can use the Oracle as a discovery tool over your whole C3 estate.

What you get

Quick start

Start the Oracle, grab your token, and connect a client.

c3 oracle serve --no-browser
# or: run it at login, no terminal window
c3 oracle serve --install

c3 oracle api info

# Claude → paste the snippet
# Any LLM → fetch openapi.json

Connect Claude (MCP)

Add the entry from c3 oracle api info to your .mcp.json (project root) or Claude Desktop config:

{
  "mcpServers": {
    "c3-oracle": {
      "type": "http",
      "url": "http://127.0.0.1:3332/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Claude lists the c3-oracle tools (list_projects, c3_search_cross, query_memory, read_graph, …). Ask it to "discover what C3 projects exist and search them for X".

Connect any LLM (OpenAPI REST)

Every tool is also a plain REST operation. Point a function-calling LLM at the spec, then call tools with the Bearer header.

# Discover the tools (OpenAPI 3.1)
curl -H "Authorization: Bearer <token>" \
     http://127.0.0.1:3331/api/discovery/openapi.json

# Invoke a tool by name
curl -X POST \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"tool":"list_projects","args":{}}' \
     http://127.0.0.1:3331/api/discovery/call

# Or use the per-tool path (body = the tool's args)
curl -X POST \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"query":"rate limiter","top_k":5}' \
     http://127.0.0.1:3331/api/discovery/tools/c3_search_cross

REST endpoints

All under /api/discovery; every request requires Authorization: Bearer <token>.

Tools & capability tiers

The exposed set is capped by api_max_tier in ~/.c3/oracle/config.json (read or action). Code-editing tools are never registered.

Read tier — discovery

Action tier — safe writes (no code edits)

Mobile & desktop companion apps

The same Oracle process also serves /api/mobile/* — a separate, Bearer-gated surface for the C3 mobile app and the C3 Desk desktop tray client (oracle/services/mobile_api.py and friends). It is capability-gated: GET /api/mobile/info reports what this Oracle build actually exposes, so a client hides a feature it cannot use instead of discovering it by trial and error. api_version is currently 5.

Per-client tokens and the loopback listener (v2.125.0)

Before v2.125.0 the gateway had one credential, the Discovery token, shared by every client. Now each client (a phone, or the C3 Desk tray app) can carry its own token:

• POST /api/mobile/clients mints one. It has no Bearer of its own; it requires a local caller plus the owner-only ~/.c3/oracle/bootstrap.key, and returns the token exactly once.
• GET /api/mobile/clients lists issued clients (hashes never included); DELETE /api/mobile/clients/<id> revokes one immediately.
• Tokens are stored as SHA-256 hashes in ~/.c3/oracle/clients.json, owner-only ACL. The Discovery token still works everywhere — it maps to a synthetic mobile client so existing phones keep working unchanged.
• Dashboard: Settings → Mobile app → Show pairing code now mints a per-device token for the QR rather than embedding the Discovery token, so rotating the Discovery token no longer un-pairs every phone. A Paired devices list lets you revoke one by one.

A loopback listener (oracle/listeners.py, config key loopback_listener, default true) solves a specific problem: if bind_host is set to a specific non-loopback address (a Tailscale IP, say), http://127.0.0.1 used to be refused even from the Oracle's own machine — which broke the same-box C3 Desk client. When bind_host is non-loopback, the same Flask app now also listens on 127.0.0.1 on the same port, with the same Host allowlist and Bearer gates. A wildcard or already-loopback bind is unchanged.

Event notifications and session boundaries (v2.126.0)

A finished background job, a local-CI run, a session ending, or the MCP runtime coming ready each write one notification with a machine-readable kind and a ref_id (services/notifications.py, EVENT_KINDS):

Every producer is best-effort: a notification failure never fails the job, run, hook or server it reports on. override.channel (mobile / desktop / both) is also consumed here, so the desktop client only toasts an override request meant for it.

Authentication & security

A single Bearer token guards both Discovery transports. The REST surface checks it in a Flask before_request hook; the MCP transport checks it in a pure-ASGI middleware (so streaming responses pass through intact). The mobile gateway (previous section) authenticates separately, with the Discovery token or a per-client token.

Where the token lives

Rate limiting and audit logging (v2.64.0)

Tool-executing routes (/call, /call/stream, /tools/<name>) sit behind a per-caller token bucket — default 60 calls/min with a quarter-minute burst (api_rate_limit_per_min, api_rate_burst; 0 disables). Listing tools, the OpenAPI document, and mcp-info stay unthrottled. Exhaustion answers 429 with Retry-After.

Every tool call also appends one line to ~/.c3/oracle/discovery_audit.jsonl (api_audit_enabled), readable via GET /api/activity/discovery. The log stores a hash of the arguments, never the arguments themselves, and identifies the caller by token fingerprint rather than the token. Auditing fails open — a broken log never breaks a call.

Rotate or revoke at any time with c3 oracle api rotate / c3 oracle api clear.

CLI commands

The Hub exposes the same controls under Settings → Oracle service (Install / Uninstall / Start / Stop / Open). Starting the Oracle from there also fills in the Hub's Oracle URL when it is empty, so the Open Oracle button appears in the top bar. That button opens a signed-in dashboard: it redeems the Oracle's owner-only bootstrap key for you. Reaching the dashboard by pasting its URL instead leaves it read-only — the page renders and the header looks healthy, but chat, Save and Test Ollama answer 401 unauthorized.

~/.c3/oracle/config.json keys

Troubleshooting