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"

Restart Codex or open a new session after changing its MCP configuration so it discovers the tools.

The dashboard snippet includes the key directly and does not require WEBREF_API_KEY. If you choose bearer_token_env_var instead, that variable must exist in the process that launches Codex. Setting it in a terminal does not necessarily make it available to the desktop app.

Recent Codex versions also support http_headers_helper, a local command that prints a JSON object of HTTP headers. An existing helper can read a stored credential and return an Authorization header without putting the key in the URL. Keep a working helper when migrating, and never print its credential-bearing output into the conversation. See the Codex configuration reference.

If you previously installed the webref CLI or a webref-search skill, follow the CLI migration guide so old instructions do not keep sending the agent to the retired command.

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 per call.

Most calls return the finished article: title, witness line, prose with quote cards checked against their pages, what was not established, and a private receipt reference. 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 of your own that continues the thread. Returns only the new section.

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

Test from the agent first: after restarting it, check that the webref server exposes research, get_research, followup, publish_receipt, and unpublish_receipt. Connecting and listing tools do not start research or consume credits.

For a direct HTTP check, initialize an MCP session first:

bash

curl -i --fail-with-body --max-time 20 https://webref.ai/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"webref-connection-check","version":"1.0"}}}'

Expect HTTP 200, serverInfo.name equal to webref, and an Mcp-Session-Id response header. Use that session ID in both requests below:

bash

curl --fail-with-body --max-time 20 https://webref.ai/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl --fail-with-body --max-time 20 https://webref.ai/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

The notification may return an empty HTTP 202 response. The final request should return all five tools. Keep the same API key and session ID throughout. Do not post credentials or credential-bearing URLs when sharing diagnostics.

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.

Environment variable is not set: If Codex names WEBREF_API_KEY or another variable, its configured bearer_token_env_var is unavailable to that Codex process. Use the dashboard snippet, make the variable available to the desktop app, or keep an existing supported credential helper. Restart Codex after the change.

400 Invalid session ID: Initialize the MCP session and reuse its Mcp-Session-Id. A standalone tools/list request is not a valid connection test.

403 with Cloudflare error 1010 or browser_signature_banned: This is an edge rejection before WebRef checks the API key. Record the failed client's name, HTTP status, cf-ray header, and response body without secrets. A shell probe and the agent's native MCP client can have different User-Agent headers, so a blocked probe does not establish that native MCP is blocked. Test the native connection and send its actual error to WebRef support if it fails.

Codex requires approval, but approval policy is never: The connection can be healthy while Codex refuses to execute a tool. Research and follow-ups create receipts, use credits, and access the public web, so they are not read-only operations. Use interactive approval. If you deliberately want these two tools to run unattended, Codex supports per-tool permission:

toml

[mcp_servers.webref.tools.research]
approval_mode = "approve"

[mcp_servers.webref.tools.followup]
approval_mode = "approve"

This allows those tools to spend available research credits without prompting. Publication tools have separate permissions. See the Codex configuration reference.

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

Connection refused: Verify internet connectivity. A sandbox shell with network access disabled can fail DNS even when the agent's native MCP connection works. Run the HTTP check from a network-enabled terminal or use native MCP discovery.