OrgRelay
orgrelay.com

Import a GraphQL API

OrgRelay reads a GraphQL schema through introspection, lists every query and mutation, and lets the owner tick the ones staff need. Queries become read tools. Mutations become write tools that always wait for approval.

Use this for platforms whose main API is GraphQL, such as Shopify's Admin API or GitHub. If the API is REST with an OpenAPI file, use OpenAPI import instead. For Shopify specifically there is already a Shopify connector with hand-written queries.

Step by step

  1. Admin → Business systems → Add connection → GraphQL import.
  2. Enter the endpoint, for example https://api.example.com/graphql, and credentials (bearer token or API key header; see authentication).
  3. OrgRelay sends one introspection query. If the server returns no schema, the usual causes are introspection disabled or a token without permission.
  4. Tick the operations to expose. Each query shows as gql.<field> and each mutation as gqlw.<field>, in snake case.
  5. Test connection, then grant the connection to roles or departments.

How operations map to tools

GraphQL OrgRelay tool Access
query { orders(first:, after:, query:) } gql.orders read
mutation { orderCancel(orderId:, reason:) } gqlw.order_cancel write · approval
  • Arguments become the tool's input schema. Enum values (up to 50) and input object fields (up to 40, two levels deep) are carried over, so the AI sees valid choices.
  • Deprecated fields are skipped.
  • Up to 100 operations per connection, the same limit as every other connector in the connector spec.

Selection sets

GraphQL needs to know which fields to return. OrgRelay builds a default selection: the scalar fields of the return type, plus nodes, edges, node and pageInfo up to two levels, which covers the Relay connection pattern most APIs use.

Each tool also accepts an optional _fields argument. The AI can pass its own selection set when the default is too thin or too wide:

_fields example
nodes { name createdAt totalPriceSet { shopMoney { amount currencyCode } } } pageInfo { hasNextPage endCursor }

Because the AI reads only about 12,000 characters of a result, asking for fewer fields usually gives better answers.

Writes and approvals

Every mutation is a write tool. When the AI wants to run one, OrgRelay creates an approval request showing the operation and its arguments. After a person approves, OrgRelay sends the mutation once. Details in approvals and write tools, and the reasoning behind a human checkpoint in human-in-the-loop for MCP.

GraphQL mutations generally have no idempotency key. If the vendor offers one (some accept a client mutation id), prefer a hand-built connector that passes OrgRelay's key through.

Rate limits

Many GraphQL APIs use cost-based throttling rather than a request count, and OrgRelay cannot see the cost of a query before sending it. Keep selections small and paginate with first and after. OrgRelay's own limit of 120 calls per minute per connection still applies on top.

When to build a connector instead

  • You need the same question answered across several systems with one tool name. Use standard tool names.
  • Queries need fixed filters the AI should not change, such as always scoping to one location.
  • The schema is very large and most of it is irrelevant.

The templates show how to wrap a few fixed GraphQL queries in an MCP server. The Shopify connector is a worked example.

Common questions

Introspection disabled? Import cannot work. Ask for a token that allows it, or build a connector with fixed queries.

Can a query be a write? Imported queries are read and mutations are write. The owner can override, but every mutation should keep approval.

Which fields come back? The default selection described above, or whatever the AI passes in _fields.

Next

  • Quickstart: run a template and pass the self-test in 15 minutes.
  • MCP overview: OrgRelay as an MCP server for staff.

Updated (Singapore time) · OrgRelay Team