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

.