Onion

Onion MCP

Give an agent a URL and an instruction in plain language. Get structured data back, from pages that defend themselves against bots.

https://mcp.onion4.ai/mcp

This address is a Model Context Protocol server, not a web page — what you are reading exists only so that arriving here in a browser tells you something. The server itself speaks to agents.

Connect

Copy this and send it to your agent. It installs the server itself, then checks that it worked — no config file to find, no client-specific syntax to look up.

Add the Onion MCP server to my tools: name it "onion", transport "http" (Streamable HTTP), URL https://mcp.onion4.ai/mcp. No API key is needed — without one it serves the public anonymous tier. If I give you a key later, send it as the header Authorization: Bearer <key>. Once it is connected, call the whoami tool and tell me what this server can do.

Trying it costs nothing and needs no account: with no key you get the anonymous tier — the same deal a visitor to the playground gets, not a crippled demo of it. A key swaps that for your plan.

Rather write the config yourself?

{
  "mcpServers": {
    "onion": {
      "url": "https://mcp.onion4.ai/mcp"
    }
  }
}

That is the whole of it. With a key, add a header:

"headers": { "Authorization": "Bearer onion_sk_…" }

Locally installed agents can run the same binary over stdio instead, taking the key from ONION_API_KEY.

Tools

`extract`	Submit an extraction; returns a job id in milliseconds. A bare URL with no instruction is valid too, and returns the page itself.
`extract_and_wait`	Submit and wait, bounded — or pass a job id to wait on one already running. Convenience; never the authority.
`extract_status`	Cheap status read: queued, processing, ready, failed.
`extract_result`	The authoritative outcome, with the payload inline when it is small.
`extract_progress`	The stages a job has been through — “still working” apart from “stuck”.
`feedback`	Say whether the answer was actually any good.
`whoami`	Anonymous or authenticated, and what the plan allows.

Arguments are checked before the call: the closed sets — mode, output format, verdict — are stated in each tool’s schema, so a client validates them rather than discovering them from a refusal. Anything your plan does not include is refused by name, never quietly dropped.

How it behaves

Extraction is asynchronous because it is a crawl plus a language-model pass — seconds to minutes. A call held open for that long would pin a connection per job and lose the work on any blip.

Outcomes stay distinct on purpose: the page had no data, the site refused the crawl and the crawl failed are three different answers, and only the last is an error. Collapsing them would teach an agent to retry what will never succeed.

This server keeps nothing. It holds no accounts, no keys and no copy of your extractions — it verifies a key against the account service and submits into the one pipeline the rest of Onion uses.