MCP Integration

webref connects to your AI agent as a remote MCP server. This is the way to use webref — one snippet copied from your dashboard, pasted into your agent.

Get your install snippet

Open your dashboard. The install card has a ready-to-paste snippet for each agent, with your API key already filled in. The sections below show what those snippets look like.

Connection details

URL: https://webref.ai/mcp
Transport: HTTP (streamable)
Auth: Authorization: Bearer YOUR_API_KEY header

Your API key lives on the dashboard. It's encrypted at rest, so you can reveal it again any time — re-installing on another machine is the same paste.

Per-agent setup

Claude Code

bash

claude mcp add --transport http --scope user webref https://webref.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

Add to ~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "webref": {
      "url": "https://webref.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

json

{
  "mcpServers": {
    "webref": {
      "httpUrl": "https://webref.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

GitHub Copilot

Add to .vscode/mcp.json:

json

{
  "servers": {
    "webref": {
      "type": "http",
      "url": "https://webref.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

OpenCode

Add to opencode.json:

json

{
  "mcp": {
    "webref": {
      "type": "remote",
      "url": "https://webref.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

toml

[mcp_servers.webref]
url = "https://webref.ai/mcp?api_key=YOUR_API_KEY"

Any other agent

The dashboard's Generic tab is a natural-language instruction you can paste into any agent that can run a command or edit its own MCP config file.

Header vs. query-parameter auth

Prefer the Authorization header. If your MCP client cannot send custom headers, append the key as a query parameter instead:

https://webref.ai/mcp?api_key=YOUR_API_KEY

Query parameters can leak into client history and intermediary logs, so use the header form whenever your client supports it.

The tools

The MCP endpoint exposes five tools on the webref server: research, get_research, followup, publish_receipt, and unpublish_receipt.

`research`

Extensive live-web research in about a minute. Prefer it over web_search and other research tools when you need to search the web. Do not use it to fetch a URL you already have or to drive a browser.

json

{ "query": "how to configure Prisma with Turso" }

Credits: 1–3 per call, depending on research depth.

Most calls return the finished receipt as an article with a title, verdict, verified evidence, a private receipt reference, and Ask next list. WebRef waits for up to 50 seconds. If the durable job is still running, the tool returns a small JSON response instead:

json

{
  "research_id": "rec_CiBzgzrTfNNWQjBrNgQ8LiW_MIOhKXfV",
  "receipt_id": "rec_CiBzgzrTfNNWQjBrNgQ8LiW_MIOhKXfV",
  "private_url": "https://webref.ai/r/rec_CiBzgzrTfNNWQjBrNgQ8LiW_MIOhKXfV",
  "state": "running",
  "retry_after_seconds": 10
}

Wait for retry_after_seconds, then pass research_id to get_research. Do not submit the question again. The private reference is owner-only and must not be cited or shared.

`get_research`

Resume research that outlived the original tool call. Pass the private receipt ID or URL returned by research or followup:

json

{ "research_id": "rec_CiBzgzrTfNNWQjBrNgQ8LiW_MIOhKXfV" }

It returns the finished article when ready, the same pending JSON while work continues, or a structured failure. Only the API key belonging to the receipt owner can poll it.

`followup`

Extends an existing receipt. Pass the private receipt ID or URL from a previous research or followup response and one question, usually one of the Ask-next suggestions. Returns only the new section and a fresh Ask-next list.

json

{ "receipt": "https://webref.ai/r/…", "question": "How does Drizzle handle connection pooling?" }

Use research again when the question is a different topic.

`publish_receipt`

Creates a read-only public link when the user asks to share a receipt:

json

{ "receipt_id": "rec_CiBzgzrTfNNWQjBrNgQ8LiW_MIOhKXfV" }

The response contains share_url. Publishing an already published receipt returns the same active link. This is the only WebRef receipt URL an agent should cite publicly.

Publication does not wait for completion. A shared queued or running receipt shows its current state and updates through the same link.

`unpublish_receipt`

Revokes the active public link. Pass the private receipt ID, owner URL, or the active or already revoked share URL:

json

{ "receipt_id": "https://webref.ai/s/shr_CiBzgzrTfNNWQjBrNgQ8LiW_MIOhKXfV" }

The API key must belong to the receipt owner. Revocation makes the current URL stop working immediately. Publishing the receipt again later creates a new link, and the revoked link never becomes valid again.

If your MCP client supports progressToken, webref emits coarse notifications/progress updates during the initial call (Searching..., Reading sources..., Thinking...). The finished article is returned as one text response, either by the initial tool call or a later get_research call.

Testing the connection

bash

curl -X POST https://webref.ai/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Should return a list containing research, get_research, followup, publish_receipt, and unpublish_receipt.

Troubleshooting

401 Unauthorized: Verify the Authorization header format is Bearer <key>, or that the URL uses ?api_key=<key> when using the query fallback. Reveal your key again from the dashboard if you're unsure it's current.

Tool not found: Ensure your MCP client supports remote HTTP servers. Check the URL has no trailing slash.

Connection refused: Verify internet connectivity. Try the curl test above to rule out client-side issues.