ask-graphql-mcp

# Ask GraphQL MCP

Use this skill to solve Web3/on-chain questions via Ask GraphQL MCP and a target GraphQL endpoint.

## Primary goal

Use MCP tools by forwarding natural-language tasks and returning endpoint-specific answers.

Do not use direct GraphQL calls as default behavior. Use MCP first.

## Hard constraint: no direct-query bypass

When this skill is triggered, always execute through Ask GraphQL MCP (`graphql_agent` or MCP JSON-RPC path), even if the model can compose GraphQL queries by itself.

Direct GraphQL execution is allowed only when user explicitly requests bypassing Ask MCP.

## Required inputs

Collect these inputs before analysis:
- User question or task (required)
- GraphQL endpoint URL (required for execution; can be discovered via `graphql-endpoint-discovery`)
- Plan mode: default `free`; switch to `paid` only when free-tier limit is reached or user explicitly asks
- API key (required for paid mode)
- Optional `X-ENDPOINT-AUTHORIZATION` when upstream endpoint is private

When endpoint URL is missing:
1. Run pre-skill `graphql-endpoint-discovery`
2. If high-confidence endpoint candidate exists, continue automatically
3. If ambiguous, ask user to confirm among top candidates
4. If no candidate, ask user for endpoint directly

## Deterministic invocation rules

Use this exact routing logic:
1. If task is Web3/on-chain related and user message includes explicit endpoint URL (`http://` or `https://`) -> call this skill directly.
2. If task is Web3/on-chain related but endpoint URL is missing -> call `graphql-endpoint-discovery` first, then return here only when endpoint is resolved.
3. If task is clearly non-Web3 and non-on-chain -> do not call this skill.
4. In one user turn, at most one execution path is allowed:
- direct `ask-graphql-mcp`, or
- `graphql-endpoint-discovery` then `ask-graphql-mcp`

Never ask user for endpoint before running `graphql-endpoint-discovery` once.
Never replace `ask-graphql-mcp` with hand-written direct GraphQL execution unless user explicitly asks to bypass MCP.

## MCP connection policy

1. Default to free gateway: `https://ask-api.hermes-subnet.ai/mcp/graphql-agent`
2. Use paid gateway only when needed: `https://ask-api.hermes-subnet.ai/mcp`
3. Always set `X-ENDPOINT` to the user endpoint
4. Set `X-ENDPOINT-AUTHORIZATION` only when upstream endpoint requires auth
5. In paid mode, include `X-API-KEY`

Use templates from `references/config-templates.md` when you need to emit copy-ready JSON.

## Agent execution workflow

1. Confirm endpoint and user objective. If endpoint is missing, run `graphql-endpoint-discovery` first.
2. Prefer session tool path: if `graphql_agent` is available in current session tool list, use it.
3. If session tool is unavailable, use HTTP JSON-RPC path to Ask MCP gateway with required headers (`X-ENDPOINT`, optional `X-ENDPOINT-AUTHORIZATION`, and `X-API-KEY` in paid mode).
4. Send the user task to MCP in natural language.
5. Timeout policy: when question complexity is high, allow MCP/agent call timeout up to 2 minutes (120s) before treating it as failed.
6. If needed, send one follow-up clarification prompt to MCP.
7. Return MCP result with concise interpretation for the user.

## HTTP JSON-RPC path (when session tool is unavailable)

Use MCP gateway endpoint:
- Free: `https://ask-api.hermes-subnet.ai/mcp/graphql-agent`
- Paid: `https://ask-api.hermes-subnet.ai/mcp`

Call sequence:
1. `tools/list` to verify `graphql_agent` is exposed by gateway
2. `tools/call` with:
- `name: "graphql_agent"`
- `arguments.question: <user natural-language request>`

This path still uses MCP, not direct GraphQL querying.

## Fallback workflow

If the task fails:
1. Validate gateway URL matches current mode (free/paid).
2. Validate `X-ENDPOINT` format and reachability.
3. Validate `X-ENDPOINT-AUTHORIZATION` for private endpoints.
4. Validate `X-API-KEY` in paid mode.
5. Retry with minimal known-good config.

If MCP returns free-tier rate limit/quota errors:
- Guide user to create API key at `https://ask.hermes-subnet.ai/billing/api-keys/`
- Switch user to paid gateway `https://ask-api.hermes-subnet.ai/mcp` with `X-API-KEY`
- Explicitly ask user to provide API key now so execution can continue immediately
- Provide a copy-ready paid config snippet with `X-API-KEY` placeholder in the same response
- Do not end with only "retry later" or "wait for reset"; API key request must come first

If paid API key quota is exceeded:
- Guide user to check usage/quota at `https://ask.hermes-subnet.ai/billing/`

## Response standard

For endpoint analysis requests, structure responses as:
1. Assumptions
2. MCP answer summary
3. Optional query/details provided by MCP
4. Next step (run/verify/debug)

For pure setup requests, provide one copy-ready JSON block plus a short verification checklist.

When mentioning quota/rate-limit failures, always include the correct billing link:
- API key creation: `https://ask.hermes-subnet.ai/billing/api-keys/`
- Usage/quota check: `https://ask.hermes-subnet.ai/billing/`

For free-tier limit errors, treat API key guidance as highest-priority next action:
- First line should clearly request API key from user
- Include API key creation link in the same message
- Include paid-mode gateway and required header keys

## Rate-limit detection and mandatory wording

Treat these as free-tier limit signals:
- `rate limit exceeded`
- `quota exceeded`
- `too many requests`
- `retryAfter`
- `429`

When any signal appears, reply with this mandatory first sentence pattern:
- `Free quota reached. Please create an API key at https://ask.hermes-subnet.ai/billing/api-keys/ and send it here so I can continue now.`

Then include:
1. Paid gateway URL: `https://ask-api.hermes-subnet.ai/mcp`
2. Required paid header: `X-API-KEY`
3. If relevant, quota page: `https://ask.hermes-subnet.ai/billing/`

For practical prompt patterns, read `references/tools-and-prompts.md`.