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 webref tool

The MCP endpoint exposes a single tool, webref. It accepts questions, URLs, or both — the planner decomposes your query into search and read actions automatically.

json

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

Works with URLs too:

json

{ "query": "summarize https://example.com/article" }

Or mix questions with URLs:

json

{ "query": "compare https://lib-a.dev/docs and https://lib-b.dev/docs for auth support" }

Credits: 1 per call. ~15 seconds.

If your MCP client supports progressToken, webref emits coarse notifications/progress updates during the run (Searching..., Reading sources..., Thinking...). The final result is returned as one normal text response.

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 webref.

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.