MCP

Install locally

graphjin mcp add codex
graphjin mcp add claude

For hosted GraphJin:

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

Tool philosophy

GraphJin’s MCP surface starts with discovery:

• Search catalog rows before writing a query.
• Ask for query syntax and examples before choosing operators.
• Inspect gj_security before writes, workflows, config changes, file access, or code changes.
• Execute through saved queries or validated GraphQL.

query_catalog and execute_saved_query use the same artifact overlay as HTTP GraphQL. With a configured artifact store and user_id, the caller sees global config files plus their own gj_artifacts rows.

Cursor IDs

MCP responses replace opaque GraphJin cursor strings with short cursor IDs when cursor caching is available. Clients pass those IDs back to execute_graphql or execute_saved_query; GraphJin expands them to the original encrypted cursor before execution.

Do not hardcode gj-, __gj-enc:, or any cursor prefix in an MCP client. GraphJin uses a dynamic security prefix, and prefix guessing can make encrypted cursor recognition fail.

{
  "name": "ProductsPage",
  "variables": {
    "cursor": "cursor_01H..."
  }
}

Production identity

HTTP MCP endpoints can be protected by OAuth or the same JWT/OIDC context as the main API. Stdio mode is useful for local development.

Capability-aware tools

The MCP tool list is catalog-first in both sources and non-sources configs. graphql_help, query_catalog, execute_saved_query, and validate_where_clause form the stable bootstrap surface; raw GraphQL and the server-side agent appear only when their MCP/agent gates enable them.

In dev mode, the config tools get_current_config, validate_config, and update_current_config are also exposed — even when the agent is the front door — so a connected AI IDE keeps first-class configuration access. These are dev-only and never appear in agentic or production deployments. See How Configuration Works for the full set of config interfaces.

For local development, named query auto-save and workflow saves fall back to config files only when there is no user_id or no artifact store.

Watch event resource

When watches are enabled, MCP exposes one caller-scoped resource:

graphjin://watch-events/unseen

Clients may subscribe to it and receive notifications/resources/updated when their own unseen watch events appear. A resource read returns compact metadata only: event IDs, watch IDs, timestamps, data hashes, truncation flags, and delivery status. Full event payloads remain behind gj_watch_event or the REST/GraphQL watch APIs.

Unsubscribing from this MCP resource only removes the in-memory resource subscription. It never pauses, expires, deletes, or cleans up watch definitions.