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.