Handigraphs Stats API MCP

Public MCP server for read-only access to the Handigraphs Stats API v1. Version 0.2.6 uses stdio only. The normal authenticated server exposes three stats tools:

• list_resources({ sport? }) discovers sports and resources.
• describe_resource({ sport, resource }) discovers metrics, canonical units, splits, and supported filters.
• query_stats(...) validates against live discovery and queries one protected data resource. Continue pagination by passing the returned cursor back to this tool.

Sports, resources, metrics, and splits are never compiled into this package. Public discovery remains authoritative.

Credentials

Create a reveal-once Stats API key at www.handigraphs.com/account/api. During rollout testing, keys beginning with hg_test_ automatically use the sandbox API; production keys beginning with hg_live_ use production. Never paste a real key into a repository, issue, prompt, or committed client configuration.

Install with the Handigraphs plugin

Codex

1. Install Node.js 22 or newer.
2. Install the latest Codex CLI and confirm the version before adding the plugin:

npm install --global @openai/codex@latest
codex --version

3. Open Terminal and run these commands in order:

codex plugin marketplace add Handigraphs/handigraphs-stats-api-mcp
codex plugin add handigraphs-stats-api@handigraphs

4. In Codex, select the plugin starter Connect my Handigraphs account. On Windows, approve the local helper launch when prompted.
5. Codex opens the plugin's secure local setup window. Use its link to create a named Stats API key, paste the reveal-once key into the masked field, and select Save. Never paste the key into the Codex conversation.
6. Fully quit and reopen Codex, then start a new task. The plugin will load the saved key automatically.

When no key is configured, the plugin intentionally starts in setup-only mode. Its setup skill launches the bundled password-masked helper through Codex's approved local-shell path on Windows and uses the argument-free configure_api_key MCP tool on macOS; Codex never receives the key. Windows stores it as a user environment variable, while macOS stores it in the user's login Keychain. See the Codex setup guide for updating, key rotation, troubleshooting, and the Linux fallback.

Claude Code

1. Install Node.js 22 or newer.
2. Create a named Stats API key and copy it when it is revealed.
3. Open Terminal and run these commands in order:

claude plugin marketplace add Handigraphs/handigraphs-stats-api-mcp
claude plugin install handigraphs-stats-api@handigraphs

4. Inside Claude Code, run /plugin configure handigraphs-stats-api@handigraphs, paste the key into the sensitive setting, and save it.
5. Run /reload-plugins or start a new Claude Code session.

Claude Desktop extension

1. Create a named Stats API key and copy it when it is revealed.
2. Download handigraphs-stats-api-mcp-<version>.mcpb from the matching GitHub release.
3. Double-click the downloaded file to open it in Claude Desktop. If it does not open, drag the file onto the Claude Desktop window.
4. Review the extension, select Install, and enter the Stats API key when prompted.
5. Start a new conversation. Select + in the message box, then Connectors, and confirm Handigraphs Stats API appears.

The bundle includes the compiled server and its production dependencies; a separate Node.js installation is not required by the extension.

These are local distributions. They do not create a hosted connector for Claude.ai, Claude Cowork, mobile clients, or ChatGPT web.

Configure another MCP client

Node.js 22 or newer is required. Add the published npm package to any client that supports local stdio MCP servers:

{
  "mcpServers": {
    "handigraphs-stats": {
      "command": "npx",
      "args": ["-y", "@handigraphs/stats-api-mcp"],
      "env": { "HANDIGRAPHS_API_KEY": "hg_live_REPLACE_ME" }
    }
  }
}

Restart the MCP client after saving its configuration. Do not commit the configuration when it contains a real key.

An hg_test_ key selects https://handigraphs-sandbox-web-49829810d1bb.herokuapp.com/api/v1 automatically. HANDIGRAPHS_API_BASE_URL remains available as an explicit override for local development or another approved environment.

Configuration

Environment variables:

| Variable | Required | Default | Purpose | | --- | --- | --- | --- | | HANDIGRAPHS_API_KEY | Yes, except for Codex on macOS | macOS Keychain fallback in Codex | Bearer key for protected data. It is never accepted as a tool argument. | | HANDIGRAPHS_API_BASE_URL | No | Inferred from key prefix | API v1 root. hg_test_ uses sandbox and other keys use https://www.handigraphs.com/api/v1; HTTPS is mandatory except loopback HTTP used by tests. | | HANDIGRAPHS_DISCOVERY_TTL_SECONDS | No | 300 | In-process public-discovery cache TTL. | | HANDIGRAPHS_HTTP_TIMEOUT_MS | No | 10000 | Upstream request timeout. | | HANDIGRAPHS_MAX_RESPONSE_BYTES | No | 5242880 | Maximum declared or streamed upstream JSON response size. |

The Codex plugin never accepts the key as a skill or MCP tool argument. Its platform-specific setup workflow launches a separate local masked process without putting the key on a process command line. Windows uses a user-approved local helper launch and saves the key and matching API environment to the current user's environment configuration. macOS uses the argument-free configure_api_key tool, sends the key to the system security utility over a private stdin pipe, stores it in the user's login Keychain, and infers the API environment from the key prefix when the MCP process reads it.

Query model

query_stats accepts sport, resource, and these optional fields: split, metrics, up to five numeric filters, sort, team, opponent, entity_id, day, page_size, cursor, stat_format, meta, category, duration, and location. Resource discovery determines which optional fields are supported. stat_format and meta default to compact.

Filter objects use { "metric": "k_pct", "operator": "gte", "value": 0.20 }. Operators are eq, ne, gt, gte, lt, and lte. Values must be finite and use the canonical unit returned by discovery; proportions use 0.20 for 20%.

Successful tools return the upstream JSON in structuredContent.response, a minified JSON text block, and safe request/quota headers in structuredContent.metadata. Upstream problem responses become isError tool results. The server does not automatically retry 429 or 503 responses.

Security behavior

• stdout is reserved exclusively for MCP protocol messages; diagnostics use stderr.
• Authorization is sent only to protected resource URLs, never public discovery.
• Redirects, credentialed base URLs, cross-origin discovery links, and links outside /api/v1 are rejected.
• Discovery uses a 300-second default cache with ETag revalidation and in-flight coalescing. Protected data and errors are never cached.
• Upstream JSON bodies are bounded by declared and streamed byte size before parsing.
• Error and diagnostic values recursively redact the configured key and authorization-like fields.

See SECURITY.md for reporting and key-handling guidance.

Development

Clone this repository and install its locked dependencies:

npm ci

Run the complete local validation suite:

npm test
npm run typecheck
npm run build
npm run pack:check
npm run distributions:check
npm run mcpb:check

Maintainers can run the sandbox-only live launch audit with a temporary hg_test_ key held only in HANDIGRAPHS_API_KEY:

npm run audit:live:sandbox

The audit uses the official MCP client over stdio, discovers both sports, describes and queries all nine resources with compact/default metadata, and verifies cursor pagination without printing response rows or the key.

Tests use local mocked HTTP servers and the official MCP client, including an end-to-end stdio process. No live Handigraphs key or external service is required.

Build a local Claude Desktop artifact in artifacts/ with:

npm run mcpb:pack

Maintainers should use the GitHub Release workflow described in docs/releasing.md rather than publishing from a local machine.

License

Licensed under the Apache License 2.0.