ask graphql mcp

AI Community

Skill notes

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)

Deterministic invocation rules

Use this exact routing logic: If task is Web3/on-chain related and user message includes explicit endpoint URL (http:// or https://) -> call this skill directly. 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. If task is clearly non-Web3 and non-on-chain -> do not call this skill. In one user turn, at most one execution path is allowed:

MCP connection policy

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

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Required · Vendor-specific
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# 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`.

---
> Source: [ComeOnOliver/skillshub](https://github.com/ComeOnOliver/skillshub) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.