GraphQL Connections

GraphQL connections expose any HTTPS GraphQL endpoint to agents. The agent runs queries via shell curl against an injected $GRAPHQL_URL env var; auth headers are stitched in by the fireshell network proxy on every request.

GraphQL APIs self-document via introspection, so a single connection works with any compliant endpoint — Sourcegraph, GitHub, Linear, Shopify, Hasura, etc.

Recommended: Create and manage connections via the web UI at https://ui.cloud.firetiger.com/settings/connections

Connection Parameters

Required Parameters

Parameter	Type	Description
`url`	string	GraphQL endpoint URL — must use `https://` (e.g., `https://api.linear.app/graphql`)

The fireshell network proxy drops plain HTTP egress, so an http:// URL will pass create-time validation but fail at runtime with no auth applied.

Authentication

Set exactly one. Auth is required at create time — even for public endpoints, set none explicitly so an unset oneof can’t yield a silently-unauthenticated connection.

Bearer Token

Standard Authorization: Bearer <token>. Covers Linear, GitHub GraphQL, and most modern GraphQL APIs.

"bearer": { "token": "<token>" }

Basic Auth

Rare for GraphQL but supported.

"basic": { "username": "user", "password": "pass" }

Static Headers

Arbitrary header map. Use this for schemes that don’t fit Bearer:

Service	Header
Sourcegraph	`Authorization: token <X>`
Shopify Admin	`X-Shopify-Access-Token: <X>`
Hasura	`X-Hasura-Admin-Secret: <X>`

"static_headers": {
  "headers": {
    "Authorization": "token <X>"
  }
}

No Authentication

For public GraphQL APIs (e.g., https://countries.trevorblades.com/).

"none": {}

Discovery

GraphQL APIs self-document via the __schema introspection query. Real-world schemas are large (Sourcegraph ~250–400KB SDL, GitHub ~600KB), so agents do not dump the full schema at once. Instead they discover in scoped steps:

Top-level Query surface (names + descriptions)
Top-level Mutation surface (only if writes are needed)
Drill into one type at a time via __type(name: "...")

This keeps the per-session token cost bounded.

Example Connection

{
  "display_name": "Sourcegraph",
  "description": "Sourcegraph instance for code search across our repos.\n\nUseful queries:\n- search(query, version: V3) → repo/file/symbol search\n- repository(name) → metadata for a single repo",
  "connection_details": {
    "graphql": {
      "url": "https://6.8.sourcegraph.com/api/graphql",
      "static_headers": {
        "headers": { "Authorization": "token <token>" }
      }
    }
  }
}

Description Field

GraphQL endpoints return HTTP 200 even when an operation fails — errors are in the JSON body. Document the most useful queries up front so agents don’t have to enumerate the schema on every run.

Best Practices

Always use HTTPS — plain HTTP is rejected at runtime
Pass variables as a separate variables object, not interpolated into the query string — avoids quoting bugs and lets the server validate types
Constrain results at the GraphQL layer (first: 25, request only the fields you need) rather than truncating large responses client-side
List the agent-relevant queries in the description so agents can skip introspection on common workflows