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.

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

In sources mode, the MCP tool list reflects the caller’s source capabilities. Catalog tools are advertised only when a kind: graphjin source enables catalog access, raw GraphQL execution follows the raw GraphQL capability/config gate, and workflow tools follow workflow capabilities.