Connect Data

Expose approved databases through GraphJin and keep source access governed by roles and policies.

Two GraphJin services

OpenNeko uses one GraphJin service for metadata and can use separate GraphJin services for customer data. Keep those roles distinct when you configure URLs, ports, and source policies.

Service	Default host port	Purpose
neko-graphjin	8089	Metadata GraphJin service used by OpenNeko itself through OPENNEKO_GRAPHJIN_URL.
graphjin	8080	Demo or customer-data GraphJin service used by agent-facing data sources.

Runtime code normalizes GraphJin base URLs to /api/v1/graphql. In host-hybrid development, containers may need host.docker.internal to reach a GraphJin service running on the host.

GraphJin roles

OpenNeko expects customer-data GraphJin services to authenticate requests with short-lived JWTs. The demo source template uses claims for sub, role, org_id, iat, and exp, with roles declared explicitly for user, admin, and service-style access.

Setting	Demo source value	Why it matters
auth	JWT	Agents and operators use scoped tokens instead of unauthenticated database access.
admin_roles	admin	Administrative GraphJin abilities are limited to admin callers.
allow_mutations	false	Customer data reads are separated from writes unless a source deliberately grants them.
allow_raw_queries	true	Discovery and analysis can use SQL-shaped questions through the governed GraphJin layer.
analytics_mode	true	The source is optimized for analytical reads.

Source template

The demo configuration uses GraphJin sources mode. The metadata source points at the OpenNeko catalog, while the AdventureWorks source is read-only and blocks sensitive tables or columns by pattern.

Shape of a governed source

mcp:
  disable: false
  allow_config_updates: true
  allow_mutations: false

sources:
  - name: adventureworks
    type: postgres
    read_only: true
    tables:
      blocklist:
        - ar_internal_metadata
        - schema_migrations
        - secret
        - password
        - encrypted
        - token

Admin gate

OpenNeko does not rely on a GraphJin root switch alone for source governance. Source configuration changes are modeled as source_config_admin actions and are routed through the approval policy engine. By default, those changes require an admin approver.

Use read-only sources by default for analytical agent work.
Add namespace rules such as org_id scoping for account-level access.
Treat source config changes as governed actions and route them through review.
Review blocked table and column patterns before exposing a production database.