Web search over MCP

The configuration

Nearly identical across clients; the file location differs, and so does the exact spelling of the URL key. Claude Code reads .mcp.json in the project root or ~/.claude.json globally; Claude Desktop uses claude_desktop_config.json; Cursor uses .cursor/mcp.json. Per-client instructions, including the clients that still need a stdio bridge, are on the documentation site.

{
  "mcpServers": {
    "unlob": {
      "type": "http",
      "url": "https://api.unlob.com/mcp?profile=grounding",
      "headers": { "x-api-key": "ulb_your_key_here" }
    }
  }
}

Keeping the key out of version control

Project-scoped configs are worth committing so a team shares the same tools — which means the key must not be in the file. Reference an environment variable and export it from your shell profile or a gitignored .env.

Keys are ulb_ followed by 48 hex characters, stored as a hash on our side and shown once. If one leaks, rotate it: rotation issues a replacement and retires the old key in one transaction, so there is never a window with two live keys or none.

What the agent gets

On the grounding profile, two tools: ground and get_document. On the default profile, every tool — the evidence layer (ground, evidence_changes), five retrieval tools (web_search, get_document, similar, browse, why_not) and six graph tools (related, corroborate, authorities, dossier, path, assemble_context).

Models handed a long tool list reach for web_search by default, which is why the grounding profile exists: with two tools the agent starts from ground, reads the receipt, and fetches only what it needs. The graph tools are where the difference from any other search MCP server lies for investigative work; the profile is how you decide when the agent sees them.

Prompting for the graph tools

A short instruction is enough, and it changes behaviour substantially: use corroborate before stating anything as fact; use why_not before concluding something does not exist; use authorities when entering an unfamiliar topic; use assemble_context when a question needs many sources rather than one.

Without this, an agent will search repeatedly and reconstruct in context what a single graph call would have answered.

When the tools do not appear

Almost always a JSON syntax error, or a missed restart — configs are read at startup. If you already had MCP servers configured, check that the new entry merged into the existing mcpServers object rather than replacing it.

In Claude Code, https://docs.unlob.com/mcp/ lists connected servers and their tools, which is the fastest way to confirm.

A word on what to expect once it is connected. Models are good at picking a tool and much weaker at picking its parameters, so a client with the full tool list available will reach for plain search far more often than for the call that would answer the question in one round trip. The first fix is the profile: connect on ?profile=grounding and there are two tools to choose between. The second is the prompt: name the tools the task actually needs and say when each applies, and the call pattern changes immediately.