GraphJin - The Governed Data Plane for AI Agents

GraphJin is a compiler and runtime that lets AI agents connect to the systems a real company already has: databases, warehouses, files, source code, workflows, metadata, and security policy. Instead of handing an agent raw credentials and hoping it guesses correctly, GraphJin gives it one governed GraphQL + MCP surface where it can discover before acting, validate queries, run approved work, and observe runtime status.

It is not only for agents. GraphJin is still a high-performance GraphQL-to-database compiler, Go library, standalone API service, REST/OpenAPI gateway, and real-time subscription server. The agent use case is where everything comes together: the same compiler that serves your apps can also give AI a smart, auditable way to work across data, code, and operations.

Works with PostgreSQL, MySQL, MongoDB, SQLite, Oracle, MSSQL, Snowflake, Redshift, BigQuery, Apache Cassandra / Amazon Keyspaces, S3/GCS/local files, CodeSQL source indexes - and models from Claude/GPT-4 to local 7B models.

Why GraphJin For Agents

• A built-in agent, one call away - POST one instruction to /api/v1/agent (or call the askgraphjinagent MCP tool) and GraphJin runs the discovery loop itself - as the caller, under the caller's permissions - and returns a typed, evidence-backed answer. See Server-Side Agent.
• One governed surface for many systems - Query operational databases, warehouses, MongoDB, object stores, local files, CodeSQL source indexes, workflows, and GraphJin system roots through GraphQL and MCP.
• Smart discovery before action - Agents start with querycatalog(search: "<user instruction>"), graphqlhelp, relationship evidence, examples, config recipes, and safety notes before writing or running queries.
• Guarded action, not raw access - Source-mode access, query allow-lists, read-only boundaries, policy-aware MCP tools, local encrypted secrets, and gj_config preview/apply keep changes auditable.
• Operational awareness - gjsecurity, gjruntime, and the built-in console expose policy and bounded runtime status so agents can check what is safe before they act.
• Durable memory and standing questions - Saved queries, fragments, and workflows live in the owner-scoped gjartifacts store; cursor-backed watches (gjwatch) run standing questions under the owner's permissions, resume from persisted subscription cursors, and deliver fired events to a durable inbox (gjwatchevent), webhooks, or workflows. Normal watches are durable by default; explicit ephemeral watches use TTL leases.

Installation

npm (all platforms)

npm install -g graphjin

macOS (Homebrew)

brew install dosco/graphjin/graphjin

Windows (Scoop)

scoop bucket add graphjin https://github.com/dosco/graphjin-scoop scoop install graphjin

Linux

Download .deb/.rpm from releases

Docker

docker pull dosco/graphjin

Try It Now

This is a quick way to try out GraphJin. The --demo flag runs a curated local demo, creates local state under the example's demo/ folder, and reuses that state on later starts. Delete demo/ to reset from scratch.

Download the source which contains the webshop demo

git clone https://github.com/dosco/graphjin cd graphjin

Now launch the Graphjin service that you installed using the install options above

graphjin serve --demo --path examples/webshop

For a larger agent-driven example with Postgres operations data, a BigQuery simulator for roast telemetry, CodeSQL over internal business code, and executable workflows:

graphjin serve --demo --path examples/coffee-roastery

More demo verticals — a MySQL corrugated-box plant with JWT roles, a PCB fab spanning Postgres + Snowflake-emu + MongoDB + a file source + an OpenAPI supplier API, and a zero-Docker SQLite clinic scheduler — live in examples/, each with an end-to-end smoke suite (make smoke-all runs them all).

You'll see output like this:

GraphJin started ───────────────────────   Web UI:      http://localhost:8080/   GraphQL:     http://localhost:8080/api/v1/graphql   REST API:    http://localhost:8080/api/v1/rest/   Workflows:   http://localhost:8080/api/v1/workflows/<name>   MCP:         http://localhost:8080/api/v1/mcp

Ask the built-in agent

With a model API key in ./.env (OPENAIAPIKEY, ANTHROPICAPIKEY, or GOOGLE_APIKEY), --demo also switches into agentic mode and enables GraphJin's built-in agent - one instruction in, a typed, evidence-backed answer out. Against the coffee-roastery demo:

curl -sS localhost:8080/api/v1/agent \
  -H 'content-type: application/json' \
  -d '{"instruction": "What production work should we prioritize next?"}'

Answers come back as {status, answer, data, evidence, actions, next}, grounded by server-side protocol guards. See Server-Side Agent below, AGENTIC.md, and graphjin.com/agentic/server-agent.

Add GraphJin To Your AI Client

Local / Dev

Use GraphJin's helper when you want one command that normalizes the URL, probes auth, and installs the right Codex or Claude config:

graphjin mcp add codex
graphjin mcp add claude
graphjin mcp add all http://localhost:8080

Defaults are client=codex, server=http://localhost:8080, and project scope. The command normalizes the server to http://localhost:8080/api/v1/mcp. Local non-TLS HTTP is correct for loopback development; hosted servers should use HTTPS.

If you prefer native client commands, add GraphJin's Streamable HTTP endpoint directly:

codex mcp add graphjin --url http://localhost:8080/api/v1/mcp
claude mcp add --transport http graphjin http://localhost:8080/api/v1/mcp

GraphJin's /api/v1/mcp endpoint is Streamable HTTP, so Claude should use --transport http for GraphJin. SSE is only for older/custom MCP servers.

Use --global when you want the MCP connection available outside the current project:

graphjin mcp add codex --global

Codex can also add non-URL stdio MCP servers with the generic command shape:

codex mcp add <server-name> -- <command> [args...]

Hosted GraphJin With OAuth

When mcp.oauth.enabled: true is configured on a hosted GraphJin server, modern MCP clients can add it by URL and handle OAuth login themselves:

codex mcp add graphjin --url https://graphjin.example.com/api/v1/mcp
claude mcp add --transport http graphjin https://graphjin.example.com/api/v1/mcp

This is the native remote-MCP path. GraphJin serves OAuth protected-resource metadata, authorization-server metadata, DCR/CIMD discovery, and MCP 401 challenges so the client can discover login automatically. See the official OpenAI Docs MCP quickstart for the Codex mcp add --url flow and the Claude Code MCP docs for Claude's HTTP transport and authentication flow.

For legacy/custom SSE servers, use Claude's SSE transport explicitly:

claude mcp add --transport sse <name> <url>
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Legacy / Current auth_login Fallback

If a server still uses GraphJin's current auth_login device-code flow instead of standards OAuth, graphjin mcp add detects that automatically:

graphjin mcp add codex https://graphjin.example.com

The command opens the device-code login, saves ~/.config/graphjin/client.json, and installs a credential-free local proxy config for the AI client. Re-run graphjin mcp setup https://graphjin.example.com later only when you want to refresh or rotate that saved CLI/proxy token.

The deprecated aliases still work for scripts:

graphjin mcp install codex https://graphjin.example.com
graphjin mcp plugin install https://graphjin.example.com   # deprecated Claude alias

Authenticate The CLI

Before graphjin cli can talk to a server, point it at one. There are no --server or --token flags — both come from a single saved config file (~/.config/graphjin/client.json, mode 0600):

graphjin cli setup http://localhost:8080            # local dev, no auth needed
graphjin cli setup https://graphjin.example.com     # signs in via the server's OIDC IdP

What setup does, depending on the server:

• No built-in login (the server has auth_login.enabled: false): saves only the URL. CLI calls send no Authorization header.
• Built-in login enabled: kicks off an RFC 8628 device-code flow. The CLI prints a verification URL + short code, opens your browser, you sign in with the configured identity provider (Google, Okta, Keycloak, Auth0-as-IdP, Azure AD — anything OIDC), and the server mints a 30-day JWT. Both URL and JWT are saved to client.json.

graphjin cli health
graphjin cli query list
graphjin cli schema tables
graphjin cli setup show       # print the saved config (token redacted)
graphjin cli setup logout     # delete client.json
graphjin cli setup            # re-run sign-in against the same server (refresh token)

To enable built-in login, set this on the server:

auth:
  type: jwt
  jwt:
    secret: "long-random-shared-secret"   # used to sign and verify local JWTs
auth_login:   enabled: true   audience_graphjin: true                 # shorthand for audience: "graphjin-cli"   oidc:     issuer_url: "https://accounts.google.com"     client_id: "..."     clientsecret: "..."                  # or $GJAUTHLOGINOIDCCLIENTSECRET     allowed_domains: ["example.com"]      # optional allow-list
mcp:   oauth:     enabled: true     mode: builtin                         # reuses auth_login identity     scopes: ["mcp"]

Successful authentication is recorded in structured logs with the verified email and name claims (when present), giving you a clean audit trail of who called every endpoint.

Getting started

To use GraphJin with your own databases you have to first create a new GraphJin app, then configure it using its config files and then launch GraphJin.

Step 1: Create New GraphJin App

graphjin new my-app

Step 2: Start the GraphJin Service

graphjin serve --path ./my-app

Step 3: Add GraphJin to an AI client

graphjin mcp add claude http://localhost:8080

Step 4: Ask Claude questions like:

• "What tables are in the database?"
• "Show me all products under $50"
• "List customers and their purchases"
• "What's the total revenue by product?"
• "Find products with 'wireless' in the name"
• "Add a new product called 'USB-C Cable' for $19.99"

How It Works

• Connects to database - Reads your schema automatically
• Discovers relationships - Foreign keys become navigable joins
• Exposes metadata - gj_* tables make discovered databases, tables, columns, relationships, functions, and indexes queryable when the GraphJin source is enabled
• Indexes source code - CodeSQL turns tree-sitter syntax trees and database references into a managed SQLite database
• Exposes MCP tools - Teach any LLM the query syntax
• Runs JS workflows - Chain multiple GraphJin MCP tools in one reusable workflow
• Compiles to SQL - Every request becomes a single optimized query

CodeSQL: Query Source Code Like a Database

CodeSQL is a managed source kind for source trees. Configure a source folder and GraphJin creates a SQLite cache under config/codesql/, indexes it with tree-sitter, and updates it on restart. In development it also watches for changes while the service runs; in production live watching is disabled.

sources:
  - name: app
    kind: sql
    type: postgres
    connection_string: postgres://app:secret@db/app
    default: true
- name: code     kind: codesql     path: /srv/app     inferdbrefs: true
- name: graphjin     kind: graphjin     metadata: true
tables:   - name: users     source: app
- name: gj_code     source: code     read_only: true

GraphJin exposes CodeSQL through one ordinary GraphQL root, gj_code. Use kind to select files, symbols, references, imports, database references, docs, parse errors, change sets, and locks:

query {
  gj_code(where: { kind: { eq: "symbol" }, name: { iregex: "handler|resolver" } }, limit: 20) {
    name
    symbol_kind
    language
    start_row
    path
    hash
  }
}

With a kind: graphjin source, GraphJin creates a read-only system graph named graphjin by default. Schema, catalog, entrypoint, capability, workflow, and system metadata are catalog items in gj_catalog; table and column metadata are selected by kind. When one CodeSQL source is active, GraphJin links catalog items to code references automatically:

query {
  gjcatalog(where: { kind: { eq: "column" }, tablename: { eq: "users" }, column_name: { eq: "email" } }) {
    database_name
    table_name
    column_name
    gj_code {
      kind
      ref_kind
      path
      symbol_id
    }
  }
}

This is where the model gets genuinely powerful: the same agent can inspect production data systems and the code that operates them. It can ask, "which handlers touch customer invoices?", "what tables do these workflows depend on?", or "show me the imports and call sites near this data path" without switching tools or inventing a new backend.

What AI Can Do

Simple queries with filters:

{ products(where: { price: { gt: 50 } }, limit: 10) { id name price } }

Nested relationships:

{   orders(limit: 5) {     id total     customer { name email }     items { quantity product { name category { name } } }   } }

Aggregations:

{ products { countid sumprice avg_price } }

Analytics directives:

{   orders {     account_id     month     total     runningtotal: total @running(aggregate: sum, by: "accountid", orderBy: { month: asc })     movingavgtotal: total @moving(aggregate: avg, rows: 6, by: "account_id", orderBy: { month: asc })     previoustotal: total @previous(by: "accountid", orderBy: { month: asc })     rankbytotal: total @rank(by: "account_id", order: desc)   } }

Mutations:

mutation {   products(insert: { name: "New Product", price: 29.99 }) { id } }

Spatial queries:

{   stores(where: { location: { st_dwithin: { point: [-122.4, 37.7], distance: 1000 } } }) {     name address   } }

Real-time Subscriptions

Get live updates when your data changes. For databases with batching support, GraphJin handles thousands of concurrent subscribers with a single database query - not one per subscriber.

subscription {
  orders(where: { userid: { eq: $userid } }) {
    id total status
    items { product { name } }
  }
}

Why it's efficient:

• Traditional approach: 1,000 subscribers = 1,000 database queries
• GraphJin: 1,000 subscribers = 1 optimized batch query
• Automatic change detection - updates only sent when data actually changes
• Built-in cursor pagination for feeds and infinite scroll

Subscribe over WebSockets (graphql-ws / graphql-transport-ws subprotocols) or Server-Sent Events — set Accept: text/event-stream on a POST /api/v1/graphql request and GraphJin streams event: next frames for each result, terminated by event: complete. Works from Node.js, Go, or any browser EventSource / WebSocket client.

Filesystem Tables (Local, S3, GCS)

Object stores show up as ordinary tables in your GraphQL schema. Declare them in config and they get the same query surface as a database table — no per-storage GraphQL plumbing on your side.

sources:
  - name: avatars
    kind: filesystem
    backend: s3
    bucket: my-bucket
    prefix: avatars/
    region: us-east-1
    presign_ttl: 15m
- name: invoices     kind: filesystem     backend: gcs     bucket: invoices     prefix: 2026/
- name: uploads_local     kind: filesystem     backend: local     root: /var/lib/graphjin/uploads
tables:   - name: avatars     source: avatars     read_only: true
- name: invoices     source: invoices     read_only: true
- name: uploads_local     source: uploads_local

Every filesystem table exposes the same columns regardless of backend:

{ avatars(
    where: { key: { like: "users/%" } }
    order_by: { key: asc }
    limit: 50
  ) {
    key size contenttype modifiedat url
  }
}
{ avatars(id: "users/42.png") {     key size url data    # data is base64 because the field was selected   } }

The legacy prefix, key, and inlinedata arguments remain accepted, but new callers should use the normal GraphJin read surface: id, where, orderby, limit, offset, first, last, after, and before. For cursor pagination, request the standard root cursor field, e.g. avatars_cursor, and pass it back through after: $cursor.

url is a presigned GET URL by default (15 min, configurable per table). Auth follows the standard credential chain: AWS env / ~/.aws / IRSA / EC2 IMDS for S3, Application Default Credentials for GCS — never embedded in GraphJin config.

Slim builds drop SDK weight: -tags nos3 or -tags nogcs excludes either backend. Custom backends register through core.OptionSetFilesystemBackend(name, factory) — same SDK GraphJin uses for the built-ins.

File Uploads

The GraphQL endpoint accepts multipart bodies per the graphql-multipart-request-spec. Files can be inlined as base64 (default) or streamed straight to a filesystem table:

uploads:
  enabled: true
  storage: avatars               # name of a filesystems[] entry; omit to inline as base64
  storagekeyprefix: "{date}/"  # {date} → YYYY/MM/DD
  maxsize: 25000_000
  allowed_mime: ["image/*", "application/pdf"]

When storage is set, the file body is written to the backend and the GraphQL variable becomes a stable reference — mutations persist this directly into a JSONB column:

{ "key": "2026/05/08/abc123.png",
  "url":  "https://s3.../...?presigned",
  "size": 12345,
  "content_type": "image/png" }

When storage is empty the variable carries the bytes inline as {filename, content_type, size, data} (base64) — useful for small uploads going straight into bytea.

Apollo Federation v2

GraphJin can register as a federation subgraph so it composes with other services behind Apollo Router / Cosmo / Hive Gateway:

federation:
  enabled: true
  version: "v2.5"
  keys:
    users: ["id"]                  # auto-derived from PKs by default
    orders: ["id", "tenant_id"]    # composite keys via override
  shareable: ["Tag.name"]          # field-level @shareable
  inaccessible: ["Users.encrypted_password"]

service { sdl } returns a federation-flavoured SDL with @link, @key, @shareable, @inaccessible, @tag, Service, and Entity. Composition succeeds out of the box; entities resolution is on the roadmap (the engine returns a clear error today, so gateways see the gap rather than silent failures).

HTTP API Routes

graphjin serve exposes everything under a single host/port. All routes go through the configured auth handler unless noted.

| Route | Methods | Purpose | |---|---|---| | /api/v1/graphql | GET, POST | GraphQL queries and mutations. Subscriptions if the request is a WebSocket upgrade or carries Accept: text/event-stream (SSE). | | /api/v1/rest/<name> | GET, POST | Run a saved/persisted query by name. Variables go in ?variables=… (GET) or the JSON body (POST). | | /api/v1/workflows/<name> | GET, POST | Legacy workflow execution endpoint. In source mode it is registered only when mcp.legacydiscovery: true; use gjworkflow_execution(insert) through GraphQL otherwise. | | /api/v1/openapi.json | GET | OpenAPI 3 spec generated from your saved REST queries. | | /api/v1/mcp | POST | MCP (Model Context Protocol) HTTP transport — Streamable HTTP, stateless. | | /api/v1/mcp/message | POST | Legacy MCP message route for older local proxy/client integrations. New clients should use /api/v1/mcp. | | /api/v1/agent | POST | Server-side agent: send one instruction, get a typed evidence-backed answer (only when agent.enabled). See Server-Side Agent. | | /.well-known/oauth-protected-resource[/api/v1/mcp] | GET | MCP OAuth protected-resource metadata (only when mcp.oauth.enabled). | | /.well-known/oauth-authorization-server | GET | Built-in MCP OAuth authorization-server metadata (only when mcp.oauth.enabled). | | /api/v1/oauth/register | POST | Built-in MCP OAuth dynamic client registration (only in builtin mode). | | /api/v1/oauth/authorize | GET | Built-in MCP OAuth authorization-code + PKCE start (only in builtin mode). | | /api/v1/oauth/token | POST | Built-in MCP OAuth token exchange/refresh (only in builtin mode). | | /api/v1/discovery | GET | Legacy discovery document. In source mode it is registered only when mcp.legacy_discovery: true; use catalog GraphQL roots otherwise. | | /api/v1/discovery/<section> | GET | Legacy discovery drill-down (e.g. tables, insights), gated the same way as /api/v1/discovery. | | /api/v1/auth/device | POST | OIDC device-flow start (only if auth_login.enabled). | | /api/v1/auth/device/token | POST | OIDC device-flow poll. | | /api/v1/auth/login | GET | OIDC login redirect. | | /api/v1/auth/callback | GET | OIDC callback. | | /health | GET | Liveness probe. No auth. | | / | GET | Built-in Web UI. Defaults on in dev and agentic modes, off in prod; set webui explicitly to override. The UI uses /api/v1/graphql and GraphJin system roots such as gjcatalog, gjsecurity, gjruntime, gjcode, and gjconfig; there is no separate admin REST API. |

Mode flags that change which routes are live:

• mcp.disable: true — removes /api/v1/mcp and /api/v1/mcp/message.
• mcp.only: true — keeps only /health and /api/v1/mcp. Legacy /api/v1/workflows/ and /api/v1/discovery* remain only when mcp.legacy_discovery: true.
• Source mode (sources: present) disables legacy /api/v1/workflows/ and /api/v1/discovery unless mcp.legacy_discovery: true.
• web_ui: false — drops / even in dev or agentic mode.

MCP Tools

GraphJin exposes a catalog-first MCP surface that guides AI models to discover before acting. The surface is caller-aware: tools/list, graphqlhelp, and querycatalog reflect the caller's visible tools, gj_* roots, catalog capabilities, and blocked/admin-only actions.

• Start goal-driven work with query_catalog(search: "<user instruction>") when it is listed.
• Inspect the best row with query_catalog(id: "...") before writing queries, choosing relationships, or using GraphJin-specific syntax.
• Use config_recipe rows for operator work; they spell out preflight, preview/apply, unsupported apply, verification, stop conditions, and forbidden patterns.
• Act through governed GraphQL roots such as gjworkflowexecution(insert), gjworkflow(insert/update/delete), and gjconfig(id: "current", update: ...) only when policy exposes them.
• In source mode, gjconfig writes must run mode: "preview" with expectedcatalogrevision, then resend the exact same payload with mode: "apply" and previewid.
• Source access and GraphJin root changes should use source_patches by exact source name instead of rewriting the full sources array.
• Watches are managed through gjwatch / gjwatch_event and REST wrappers (/api/v1/watches, /api/v1/watch-events/unseen). MCP clients can subscribe to graphjin://watch-events/unseen for caller-scoped unseen-event notifications; unsubscribing does not pause or delete durable watches.
• Use /api/v1/watches/cleanup-preview before /api/v1/watches/cleanup-apply. Expired ephemeral watches can be expired automatically, but durable watch deletion is always explicit.
• Legacy discovery tools are migration shims and are disabled unless mcp.legacy_discovery: true.

For teams building MCP agents, internal copilots, workflow agents, or enterprise automation, see AGENTIC.md. It explains the catalog-first agent loop in detail: discover, inspect, validate, act, observe, and refine.

Key discovery tools, when listed for the caller:

• graphql_help to choose a catalog-backed topic route when the task is broad or unclear
• querycatalog to search schema, relationship, workflow, language, configrecipe, config, policy, capability, and query-pattern items. Use search for ranked text discovery and where for exact filters.
• query_catalog(id: "...") to inspect evidence, examples, details, safety notes, and graph edges for one row
• validatewhereclause to validate filters before execution

• query_catalog with where: { kind: { eq: "workflow" } } to discover reusable workflows
• graphqlhelp(for: "workflowruntime") and workflow catalog rows to discover exactly which globals/functions are available inside workflow scripts
• gjworkflowexecution(insert: { workflowname: "...", variables: {...} }) to run ./workflows/<name>.js through GraphQL. This is mutation-only and returns an ephemeral result row; it does not store run history. Mark the workflows source or gjworkflowexecution table readonly to block it. The executeworkflow MCP compatibility tool is available only when mcp.legacydiscovery: true and mcp.allowworkflowexecution: true.

Server-Side Agent

Optional: instead of your client chaining querycatalog → validatewhereclause → executesavedquery, let GraphJin run the catalog-first discovery loop for you. When enabled, GraphJin exposes one MCP tool askgraphjin_agent and one REST endpoint POST /api/v1/agent that take a single instruction and return a typed, evidence-backed answer (status, answer, data, evidence, actions, next).

• Enable by loading agentic.yml (GOENV=agentic) with agent.enabled: true plus a provider, model, and apikey_env.
• Execution control: there are no per-request agent modes. agent.readonly: true forces the server-side agent to reject mutations, including saved-query mutations; otherwise core roles, row-level security, source/table readonly, and Go protocol guards decide what can run.
• Caller-scoped: the agent runs as the caller, so core roles + row-level security enforce access. The caller's role only changes which guidance the agent follows, never what it can read or write.
• Grounded: Go protocol guards keep every answer backed by real catalog/validation/execution evidence and downgrade to blocked (with evidence) when a step is skipped.
• Machine-actionable refusals: blocked responses carry a structured refusal (code, reasons, unblock steps, policy_final/retryable) so a calling agent can course-correct in one step instead of guessing.
• Model sampling: with agent.sampling: auto (or require), the agent borrows the calling MCP client's model via MCP sampling — no server-side model key needed; caller identity and permissions are unchanged.

function main(input) {
  const tables = gj.tools.queryCatalog({
    where: { kind: { eq: "table" } }
  }).cards;
  const top = gj.tools.executeSavedQuery({
    name: "top_customers",
    variables: { limit: input.limit || 5 }
  });
  return { tables, top };
}

mutation {
  gjworkflowexecution(insert: {
    workflowname: "customerinsights"
    variables: { limit: 5 }
  }) {
    status
    result_json
    error
  }
}

identity:
  useridclaim: sub
  role_claims: [role, roles]
  namespaceclaim: accountid
sources:   - name: app     kind: database     access:       read: account       write: blocked       delete: blocked       namespacecolumn: accountid

caching:
  ttl: 3600          # hard expiry in seconds
  fresh_ttl: 300     # soft expiry — entries past this trigger SWR refresh

go get github.com/dosco/graphjin/core/v3

db, _ := sql.Open("pgx", "postgres://localhost/myapp")
gj, _ := core.NewGraphJin(nil, db)
res, _ := gj.GraphQL(ctx, { users { id email } }, nil, nil)

brew install dosco/graphjin/graphjin  # Mac
graphjin new myapp && cd myapp
graphjin serve