v3 · Apache 2.0
The context layer for your AI agents.
Most teams hand-wire a brittle API or tool for every question an agent might ask. GraphJin gives agents one governed graph to explore instead - every database, file, API, and your own source code, joined in a single GraphQL query that's simpler than SQL.
Explore within bounds - one config controls what every agent can discover, query, run, change, and never touch. Or skip the wiring - a built-in agent turns one instruction into an evidence-backed answer.
The problem
Your agent is only as good as what it can see.
A capable model still enters your stack blind. It doesn't know your schema, your permissions, your saved queries, or where a field is written in code - so it works from memory and guesses.
A tool for every question
You hand-write a brittle API or MCP tool for each thing an agent might ask. The surface never keeps up, and every new question is new glue code.
Guesses, not facts
Without a map, agents invent joins, fake fields, and confuse API shape with database shape. Every translation is a chance to drift.
Too risky for production
Handing an agent raw credentials means hoping it guesses right - so it stays read-only, shallow, or boxed out of the systems that matter.
The fix isn't a smarter prompt. It's giving the agent the map - and the guardrails.
What GraphJin is
One graph your agent can explore - within bounds you set.
Instead of brittle hand-written APIs, point GraphJin at the systems you already run. It auto-learns the shape and exposes one governed graph the agent can explore: a single GraphQL query - far simpler than SQL for most models - across every database, file, remote API, and your own source code, including the relationships across them.
Explore, don't guess
Discover schemas, relationships, and examples from the live system, not from memory.
One query, every system
Databases, files, APIs, and code join in a single request.
Within bounds
One config decides what each agent can see, run, and change.
There's nothing else that turns your data and your code into one governed surface an agent can safely explore.
See it work
Ask in plain English. Get real data back.
Claude Desktop, Codex, or any MCP client talks to GraphJin. The agent discovers the shape, validates its query, and GraphJin compiles it into one optimized database query - then answers with rows it can reason over.
discover -> customers · purchases · products (2 relationships)validate -> filters ok on customers, purchases · order_by total_spent{ customers { id full_name email purchases { quantity product { price } } } }one optimized query, no N+1, no resolvers
SELECT json_agg(__sj.json) AS customers
FROM customers AS c
LEFT JOIN LATERAL (
SELECT sum(p.quantity * pr.price) AS total_spent
FROM purchases p
JOIN products pr ON pr.id = p.product_id
WHERE p.customer_id = c.id
) __agg ON true
ORDER BY __agg.total_spent DESC NULLS LAST
LIMIT 5;Done
Based on the purchase data, here are the top customers ranked by total spend:
Antwan Friesen is the top customer with almost $1,000 in purchases, about 60% more than the runner-up.
Built-in agent
One instruction in. One evidence-backed answer out.
Above, an external client drives the loop, tool call by tool call. GraphJin can also run that loop itself. POST one instruction - the built-in agent discovers, validates, and executes inside GraphJin, as the caller, under the caller's permissions - and returns a typed answer your code can branch on. No orchestration framework, no tool wiring.
# enable once in agentic.yml:
# agent: { enabled: true, provider: openai,
# model: gpt-4.1-mini, api_key_env: OPENAI_API_KEY }
curl -sS localhost:8080/api/v1/agent \
-H 'content-type: application/json' \
-d '{"instruction": "What production work should we prioritize next?"}'{
"status": "answered",
"answer": "Three open production orders, in priority order: 420 bags of Northstar House Blend 340g, 80 bags of Harbor Espresso 1kg, and 160 bags of Dawn Patrol Single Origin 250g. Start the Northstar run - priority 1, largest committed volume.",
"data": [
{ "priority": 1, "product_name": "Northstar House Blend 340g", "quantity_bags": 420 },
{ "priority": 2, "product_name": "Harbor Espresso 1kg", "quantity_bags": 80 },
{ "priority": 3, "product_name": "Dawn Patrol Single Origin 250g", "quantity_bags": 160 }
],
"evidence": {
"protocol": {
"catalog_ids": ["table:ops:public.production_orders"],
"executions": [{ "has_data": true }]
}
},
"actions": [
{ "step": 1, "tool": "query_catalog", "status": "ok" },
{ "step": 2, "tool": "execute_graphql", "status": "ok" }
]
}Runs as the caller
The agent inherits the request's identity. Core roles and row-level security decide what it can read or write - the same enforcement as any GraphQL request, with a capability profile that can't be spoofed from a request body.
Answers it can't fake
Protocol guards in Go force discovery, validation, and evidence before execution. Skip a step and answered downgrades to blocked - with a machine-actionable refusal naming the exact unblock steps, not a lecture. Watch one get caught.
Any code-capable model
The loop is generated JavaScript in a sandbox, not provider function-calling. Point agent.base_url at any OpenAI-compatible endpoint - vLLM, Ollama, OpenRouter, a local 7B - or set agent.sampling: auto and borrow the calling MCP client's model. No server-side key at all.
Answers it can't fake
The model made up an answer. The ledger caught it.
A real run against the coffee-roastery demo. Every real tool call goes through Go, which keeps its own ledger of what actually happened - what was discovered, what ran, what returned data. The model's words never write that ledger, and after the run GraphJin cross-checks every claim against it. Deterministically, in Go - where a clever prompt can't reach.
The query never runs
"Which roast batches should be held for quality review?" The model reaches for the saved query but skips the required detail inspection, so the guard rejects the call. No rows ever come back.
The model invents a table
Instead of reporting the miss, it writes a confident quality-review table - batch codes, reasons, recommendations. Plausible, well-formatted, and completely made up.
Go checks the ledger
No successful execution in the ledger means the claims have no evidence. GraphJin flips answered to blocked and returns the refusal on the right - the fake table never leaves the server.
{
"status": "blocked",
"refusal": {
"code": "saved_query_detail_required",
"blocked_action": "execute_saved_query",
"because": [
"protocol violation: inspect query_catalog(id: \"saved_query:batch_quality_snapshot\") before execute_saved_query"
],
"unblock": [
{
"tool": "query_catalog",
"args": { "id": "saved_query:batch_quality_snapshot" },
"reason": "Inspect the saved query detail before executing it."
}
],
"lawful_alternative": "Inspect the saved query detail first, then execute the approved saved query.",
"retryable": true
}
}Captured live. The actual response from this run - trimmed, not retouched. The refusal is machine-actionable: it names the exact unblock step, so a calling agent corrects course and retries instead of guessing.
The smoke suite jailbreak-tests this in every demo vertical. A model told to skip discovery and mutate anyway gets status: "blocked" and a machine-actionable refusal with unblock steps - asserted end-to-end on every smoke run. Watch the loop live: every demo streams each tool call - green dot or red - at localhost:8080/agent.
Demo verticals
Five demos. Real domains. One command each.
Not toy schemas - each demo boots a full vertical: schema, seeded operational data, saved queries, workflows, and the agent wired in. Seeds anchor to today, so the data never goes stale. Delete the demo/ folder to reset. Pick a domain and start interrogating it.
Coffee roastery
Roast schedules, cupping scores, sensor telemetry, production orders - the flagship agentic demo.
"Which roast batch should be held for quality - and why?"
graphjin serve --demo --path examples/coffee-roasteryClinic scheduler
Appointments, waitlists, no-shows - built into the binary; boots in seconds, no clone, no containers.
"Who should get the next open cardiology slot?"
graphjin serve --demoCorrugated plant
Work orders, corrugator runs, downtime, quality holds - behind real role-gated auth.
"Which work orders should the corrugator run first?"
graphjin serve --demo --path examples/corrugated-plantPCB fab
Fab orders, yield analytics, test measurements, Gerber files, a live supplier API - one graph.
"Which fab order should we release next - and what's the evidence?"
graphjin serve --demo --path examples/pcb-fabJust want the classic GraphQL starter? webshop - single Postgres, RBAC, a Stripe-style remote join, recursive comments. graphjin serve --demo --path examples/webshop
Databases
Works with all your databases.
And more.
Point GraphJin at as many systems as you need - Postgres for users, MySQL for orders, Snowflake, Redshift, and BigQuery for analytics, Cassandra or Keyspaces for CQL workloads, MongoDB for events, HTTP APIs for remote services, object storage for files, and CodeSQL for source trees - and query them through a single GraphQL endpoint. Joins, remote joins, subscriptions, search, and mutations compose across systems in one request, so an AI assistant can reason across the data, APIs, files, and code without learning every backend.
PostgreSQL
MySQL
MariaDB
MongoDB
SQLite
SQL Server
Oracle
CockroachDB
YugabyteDB
Snowflake
Redshift
BQ
BigQuery
C*
Cassandra / Keyspaces
AWS Aurora
Cloud SQL
API
HTTP APIs
OBJ
S3 / GCS / Files
{ }
CodeHow it works
One compiler. Any system. Any client.
Point GraphJin at databases, object storage, source trees, and remote APIs. It's a compiler, not a resolver framework: it learns the live shape, plans the work, and emits one optimized database operation - then enforces RBAC and serves AI assistants, REST clients, and federated routers from the same engine. No N+1, no resolver code, test-backed against real compiler paths.
The agent loop
Discover, check, validate, act.
GraphJin is the operating graph agents use to understand a real organization. It auto-learns the live surface, compiles GraphQL into database and source-backed work, and keeps policy visible enough for both humans and models to inspect.
gj_catalog
Find schemas, relationships, syntax, workflows, capabilities, examples, and evidence before choosing a path.
gj_security
Read effective policy and high-risk findings before config, workflow, file, code, or mutation actions.
preview
Validate filters, inspect generated work, run approved workflows, or preview CodeSQL changes before applying.
governed surface
Execute through GraphQL, MCP, saved queries, workflows, and guarded source operations instead of raw credentials.
Security model
Safer agents, not smaller agents.
GraphJin makes agents safer by giving them explicit boundaries, not by making them blind. Agents can explore more of the live organization because policy, evidence, and action paths are inspectable and enforced.
One config defines the AI surface.
Humans can review and diff the policy. Models can inspect the same posture through gj_catalog and gj_security before acting. GraphJin enforces that policy across GraphQL, MCP, workflows, code, files, APIs, and databases.
RBAC and row filters
Roles, table permissions, column blocks, automatic filters, and mutation limits are enforced inside the compiler.
Saved queries and allow-lists
Production agents can run named, reviewed query contracts instead of inventing arbitrary operations at runtime.
Read-only source boundaries
Filesystems, CodeSQL, databases, and control-plane tables can expose discovery without granting writes.
Preview before change
CodeSQL change sets require file hashes, exact ranges, old text, optional locks, and a preview/apply loop.
AI integration
Connect any agent over MCP, in one command.
GraphJin ships a built-in Model Context Protocol (MCP) server - so Claude, Codex, or any MCP client can explore and query your data through the same governed surface.
One command wires GraphJin into Claude Desktop, Codex, or any MCP host. From there the agent discovers what exists, validates its query, checks policy, and runs only what you've approved - no hand-written tool for every question.
Run it locally for development, or as a hosted HTTP endpoint for your team - gated by MCP OAuth or the same JWT/OIDC identity as the main API.
Code intelligence
CodeSQL: query your code as well.
CodeSQL indexes your source tree into a read-only SQLite graph. Agents can ask where a column is used, which code references it, which symbol owns that reference, and what guarded change set would update it - all through the same GraphQL interface.
users.email used?query {
gj_code(where: {
name: { eq: "users.email" }
kind: { eq: "db_ref" }
}) {
path
symbol_name
}
}kind=filekind=symbolkind=db_refkind=docIn the box
A full backend, not just an agent gateway.
The same binary and config that govern the AI surface also run your realtime, files, remote APIs, auth, and federation - no extra services to operate.
Files as tables
Uploads stream to local disk, S3, R2, or GCS; each bucket is a queryable table you can join with the rest of your schema.
Remote APIs
Drop in an OpenAPI 3 spec and its operations become joinable, RBAC-aware fields with per-spec auth caching.
Realtime
Subscribe with the same GraphQL; cursor-based SSE and WebSocket streams resume after a drop, with polls batched into one statement.
Authentication
JWT and OIDC from Auth0, Firebase, Okta, or any JWKS - one auth pipeline across HTTP, WebSocket, SSE, and MCP.
Workflows
Discover approved workflows and run them through GraphQL, REST, MCP, or the CLI.
Caching
Response caching on Redis with an in-memory fallback and stale-while-revalidate.
One binary CLI
Dev server, database toolchain, device-code login, and MCP wiring. What runs in CI matches production.
Federation
Advanced: flip a flag and every keyed table becomes an Apollo Federation v2 subgraph.
Get started
Run it in two minutes.
Three commands: install, boot a real demo, connect your agent.
Install the binary
curl -fsSL https://graphjin.com/install.sh | bashOr brew install dosco/graphjin/graphjin
Boot the built-in demo
graphjin serve --demoThe binary ships with the clinic-scheduler demo - SQLite, no Docker, no clone; it extracts to ./graphjin-demo with seeded data, saved queries, and workflows. Drop a model key in ./.env (OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_APIKEY) and the built-in agent switches on automatically. Want the flagship vertical? Clone the repo and run graphjin serve --demo --path examples/coffee-roastery.
Connect your AI client
graphjin mcp add claudeUsing Codex? graphjin mcp add codex
That's it. Open the web console at localhost:8083 - chat with the built-in agent at localhost:8083/agent, or ask from your MCP client. Real schema, real rows, evidence-backed answers.