---
name: thegraph-token-mcp-skill
description: Use The Graph Token API MCP through UXC for token metadata, wallet balances, transfers, holders, pools, and market data with help-first inspection and Token API specific JWT bearer auth binding.
---

# The Graph Token MCP Skill

Use this skill to run The Graph Token API MCP operations through `uxc`.

Reuse the `uxc` skill for generic protocol discovery, envelope parsing, and error handling rules.

## Prerequisites

- `uxc` is installed and available in `PATH`.
- Network access to `https://token-api.mcp.thegraph.com/`.
- A The Graph Token API `API TOKEN (JWT)` from `https://thegraph.market/dashboard` is available for authenticated calls.

Important auth distinction:

- Do not reuse the `thegraph-mcp-skill` API key directly.
- `thegraph-token-mcp-skill` uses a separate credential sourced from The Graph Market Token API dashboard.
- The value used with `Authorization: Bearer ...` must be the generated `API TOKEN (JWT)`, not the raw dashboard API key.

## Core Workflow

1. Verify endpoint and protocol with help-first probing:
   - `uxc https://token-api.mcp.thegraph.com/ -h`
   - Confirm protocol is MCP (`protocol == "mcp"` in envelope).
2. Configure a dedicated Token API JWT credential and binding:
   - Generate the `API TOKEN (JWT)` in `https://thegraph.market/dashboard`
   - Store it separately from the subgraph credential, for example:
     - `uxc auth credential set thegraph-token --secret-env THEGRAPH_TOKEN_API_JWT`
   - Bind the Token API endpoint to that dedicated credential:
     - `uxc auth binding add --id thegraph-token-mcp --host token-api.mcp.thegraph.com --scheme https --credential thegraph-token --priority 100`
3. Use fixed link command by default:
   - `command -v thegraph-token-mcp-cli`
   - If missing, create it:
     - `uxc link thegraph-token-mcp-cli https://token-api.mcp.thegraph.com/`
   - `thegraph-token-mcp-cli -h`
4. Inspect operation schema before execution:
   - `thegraph-token-mcp-cli getV1Networks -h`
   - `thegraph-token-mcp-cli getV1EvmTokens -h`
   - `thegraph-token-mcp-cli getV1EvmBalances -h`
5. Prefer read operations first, then narrower wallet/token/pool queries.

## Capability Map

- Service discovery:
  - `getV1Health`
  - `getV1Version`
  - `getV1Networks`
- Token data:
  - `getV1EvmTokens`
  - `getV1EvmTokensNative`
- Wallet and transfer data:
  - `getV1EvmBalances`
  - transfer/history operations exposed by the endpoint
- Market and DEX data:
  - pool / OHLC / dex operations exposed by the endpoint
- Non-EVM coverage:
  - TVM and other chain families exposed by the endpoint

Always inspect host help and operation help in the current endpoint version before relying on an operation name or argument shape.

## Recommended Usage Pattern

1. Start with network discovery:
   - `thegraph-token-mcp-cli getV1Networks`
2. Confirm the operation and required arguments with `-h`.
3. Query the narrowest surface first:
   - token metadata for one contract
   - balances for one address
   - one pool / one token / one date range
4. Expand to broader scans only when needed.

## Guardrails

- Keep automation on JSON output envelope; do not rely on `--text`.
- Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`.
- Use `thegraph-token-mcp-cli` as default command path.
- `thegraph-token-mcp-cli <operation> ...` is equivalent to `uxc https://token-api.mcp.thegraph.com/ <operation> ...` when the same auth binding is configured.
- Use direct `uxc "<endpoint>" ...` only as temporary fallback when link setup is unavailable.
- Prefer `key=value` for simple arguments and positional JSON for nested objects.
- If auth fails:
  - confirm `uxc auth credential info thegraph-token` succeeds
  - confirm `uxc auth binding match https://token-api.mcp.thegraph.com/` resolves to `thegraph-token`
  - confirm the stored secret is the generated `API TOKEN (JWT)`, not the raw API key from The Graph Market dashboard
  - rerun `thegraph-token-mcp-cli -h`

## Tested Real Scenario

The endpoint was verified through `uxc` host discovery and returned a live MCP tool list including:

- `getV1Health`
- `getV1Version`
- `getV1Networks`
- `getV1EvmTokens`
- `getV1EvmTokensNative`
- `getV1EvmBalances`

This confirms the skill target is a real MCP surface rather than a direct OpenAPI host.

The Token API requires its own bearer token workflow:

- manage the token in `https://thegraph.market/dashboard`
- generate `API TOKEN (JWT)` from the dashboard-managed Token API key
- store that JWT separately from the subgraph MCP credential

Do not document or implement this skill as if it reused the same raw API key as `thegraph-mcp-skill`.

## References

- Invocation patterns:
  - `references/usage-patterns.md`