Configuration

Environment variables, version pinning, and what to do when a tool doesn't show up.

Environment variables

Variable	Required	Default	Notes
ONTO_API_KEY	yes	—	Your live key from app.buildonto.dev/read/keys. Starts with onto_sk_live_.
ONTO_API_BASE	no	https://api.buildonto.dev	Override only if you self-host. Must include scheme, no trailing slash.

Set these in the env block of your MCP host config — never as plain command-line args (some hosts log args).

Versioning & auto-updates

Use the @latest tag so you always launch the newest server —npx -y @ontosdk/mcp@latest. This is what every example on this site uses, and it's what you want unless you have a reason to freeze.

⚠

Don't drop the tag. Plain npx -y @ontosdk/mcp (no @latest) does not auto-update — npx caches the first version it ever fetched and reuses it indefinitely, so you can silently sit on an old build and miss new tools. The @latest suffix forces npx to resolve the newest version on each launch. If you already pulled an old copy, clear it with npx clear-npx-cache (and remove any global install via npm uninstall -g @ontosdk/mcp, which would otherwise shadow npx).

To pin a specific version instead (for reproducible production agents), use an exact version suffix:

json

"args": ["-y", "@ontosdk/mcp@1.5.0"]

ℹ

Current version: 1.5.0. Six tools: read_url, score_url, read_and_score, batch, map_site, and extract_data. The core read/score surface is stable; minor bumps add tools or ship bug fixes. Since 1.5.0 the server also checks for a newer published version on launch and surfaces a one-line nudge to restart.

Self-hosting the backend

Enterprise customers can point the MCP server at a self-hosted Read API by setting ONTO_API_BASE:

json

"env": {
  "ONTO_API_KEY": "onto_sk_live_…",
  "ONTO_API_BASE": "https://onto.internal.acme.com"
}

The target must implement the public Read API contract (/v1/read, /v1/score, /v1/read-and-score). Contact founder@buildonto.dev for self-hosted access.

Troubleshooting

Tools don't appear after restart.

Confirm the host was fully quit, not just window-closed.
Validate the JSON — a single trailing comma will silently break the entire mcpServers block on some hosts.
Check the host's MCP log for connection errors. On Claude Desktop: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\ (Windows).
Make sure npx is on the host's PATH (issue on macOS when the host was launched from Finder rather than terminal).

"Invalid Onto API key".

Re-copy the key from app.buildonto.dev/read/keys. If you rotated keys recently, the host config may still have the old value.

"Monthly quota exceeded".

You've hit the monthly request cap. Upgrade at app.buildonto.dev/read/billing, or wait for the monthly reset. Paid tiers can also top up with credit packs.

"Request timed out".

The target site is slow or unreachable. The Read API has a 15-second hard timeout per request. Retry, or try a different URL.

Pricing and quotas

MCP calls count against the same monthly request budget as direct Read API calls. There is no separate MCP pricing.

Tier	Monthly requests	Price
Free	1,000	$0
Starter	10,000	$9
Growth	100,000	$49
Scale	500,000	$250
Enterprise	Custom	Contact sales

Full quota and credit-pack details: Rate limits + credits.