Available Tools

The Ontyx MCP server exposes a small set of geospatial reference tools. All tools require an API key with the read:data scope — the key you generated in the dashboard carries this scope by default.

Each tool call counts as 1 usage unit against your monthly quota. The response includes a quota envelope so your agent can surface remaining headroom.

Tool	Input	Returns
`get_population`	`{ zip: string }` (5-digit US zip)	`{ ok, zip, city, state, population }`
`get_average_income`	`{ zip: string }` (5-digit US zip)	`{ ok, zip, city, state, averageHouseholdIncome, currency: "USD" }`

The MVP launch ships these two demographic lookups. Geospatial primitives (H3 cells, feature lookup, dataset metadata) land in a follow-up release once the upstream parquet datasets are staged.

Example

> What's the population of zip code 94110?

The agent picks get_population, sends { "zip": "94110" }, and Ontyx responds:

{
  "ok": true,
  "zip": "94110",
  "city": "San Francisco",
  "state": "CA",
  "population": 73826,
  "quota": {
    "used": 12,
    "limit": 1000,
    "percent": 1,
    "state": "ok",
    "period": "2026-05"
  }
}

For zips outside the launch fixture, ok is false and reason is "unknown_zip". Invalid inputs (non-5-digit zips) are rejected at the MCP protocol layer before the tool runs.

Scope requirements

Every API key you create is granted the read:data scope by default. This scope is required for all data tools. A future release may introduce write scopes for annotation workflows; existing keys are unaffected.

If a tool call fails with an authentication error, verify that:

ONTYX_API_KEY is set correctly in your MCP server config.
The key has not been revoked — check the Dashboard API Keys section.
Your subscription is active — inactive subscriptions are rejected at the MCP gateway (HTTP 402).

Error handling

Tool errors come back as structured JSON inside the MCP tool result. Common codes:

UNAUTHENTICATED — the bearer token was missing, malformed, or revoked
SUBSCRIPTION_REQUIRED — the key is valid but the owning account has no active subscription
RATE_LIMITED — too many requests in too short a window; the envelope carries a retryAfterMs hint
QUOTA_EXCEEDED — only emitted when hard-stop policy is enabled; the MVP default is soft overage (the call succeeds and the warning rides along in the quota envelope)
INVALID_REQUEST — the input failed validation (e.g., zip is not 5 digits) or the unknown_zip fixture miss surfaced as a tool-level error

See API Reference for the full envelope schema.

Quickstart Authentication