MCP Server
The official Onto Model Context Protocol server. Plug clean URL reading and AIO scoring into Claude Code, Claude Desktop, Cursor, Cline, Zed, Continue, Windsurf, opencode — any MCP-compatible client.
@ontosdk/mcp. Runs locally over stdio via npx -y @ontosdk/mcp@latest — no daemon, no port, no install step. Listed in the public MCP registry as io.github.ravixalgorithm/onto.What is the Onto MCP server?
The @ontosdk/mcp package is a thin MCP wrapper around the Onto Read API. It exposes six tools — read_url, score_url, read_and_score, batch, map_site, and extract_data — so any agent that speaks MCP can read websites cleanly instead of parsing hundreds of KB of React noise to find a few KB of actual content.
The server runs on the same hosted backend (api.buildonto.dev), uses the same per-user API key, and counts against the same monthly quota as direct Read API calls.
Two ways to connect
Onto speaks MCP over two transports. Both expose the same six tools and bill the same account — pick the one that matches your client.
| Remote connector (OAuth) | Local server (npx) | |
|---|---|---|
| Add it with | One URL + OAuth sign-in | A mcpServers config block + API key |
| Best for | ChatGPT, Claude, hosted MCP clients | Claude Code, Cursor, Cline, Zed, local IDEs |
| Auth | Sign in with your Onto account | ONTO_API_KEY in env |
| Guide | Remote connector → | Per-client guides below |
https://api.buildonto.dev/mcp, authorize with your Onto account, and you're done. No install, no key to paste.When to use it
| Use the MCP server when… | Use the Read API directly when… |
|---|---|
| You're using an MCP-compatible client (Claude Code, Claude Desktop, Cursor, Cline, Zed, Continue, Windsurf) and want the agent to fetch URLs itself. | You're building a backend, batch job, or your own agent — anywhere you control the HTTP layer. |
| You want zero application code — just edit a JSON config file. | You want fine-grained control over caching, retries, streaming, or response format. |
| Users of your IDE / chat should be able to say "read this URL" and have it work. | You need higher throughput than a single MCP stdio process can drive. |
Install in your client
Pick your client. The hosted connector takes a URL + OAuth; the local clients each take one config block plus a restart.
Tools exposed
| Tool | What it returns | Typical use |
|---|---|---|
| read_url | Clean Markdown + extraction stats (size, reduction %, cache state). | Agent needs the content of a URL and nothing else. |
| score_url | AIO score (0–100), letter grade, hallucination risk, penalties, benefits, recs. | Agent is deciding whether to trust a source before quoting it. |
| read_and_score | Both of the above in a single call. | Default for agentic workflows — let the model decide based on score and content. |
| batch | Reads, scores, or extracts many URLs — an explicit list or a whole auto-discovered site — in one call. | Pull a whole site without burning a credit per URL; billed as a single request. |
| map_site | A site's URLs, discovered from sitemap.xml (falling back to on-page links), without reading them. | Plan a crawl — see what's there before spending reads on it. |
| extract_data | Structured data the page already declares — JSON-LD, OpenGraph, meta — plus the AIO score. Deterministic, no AI. | Pull reliable facts (prices, products, articles) when the source publishes structured data. |
Full input schemas and example responses on the Tools reference page.
MCP vs Read API directly
The MCP server is a transport. Under the hood every tool call hits the same POST /v1/read, POST /v1/score, or POST /v1/read-and-score endpoint documented in the Read API reference. Pricing, quotas, error codes, and the AIO scoring model are identical.
# These two are equivalent in everything but transport:
# 1. Via MCP (agent calls the tool):
# read_url({ url: 'https://stripe.com/pricing' })
# 2. Via HTTP (you call the API):
curl -X POST https://api.buildonto.dev/v1/read \
-H 'Authorization: Bearer $ONTO_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"url": "https://stripe.com/pricing"}'