MCP Server

Give Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any Model-Context-Protocol client native access to 13.3M company profiles, real-time enrichment, and lookalike search. Ships in the same pip install webscans.

What is MCP?

Model Context Protocol is Anthropic's open standard for connecting LLMs to external tools. Any MCP client (Claude Desktop, Cursor, custom agents built with the MCP SDK) can call any MCP server's tools with zero glue code.

The WebScans MCP server exposes 7 LLM-optimized tools so your agent can find companies, look up domains, and enrich data on the fly during a conversation.

Install

# SDK + CLI + MCP
pip install "webscans[mcp]"

# Confirm it runs
webscans mcp --help

Configure a client

Every MCP client uses the same JSON shape — command + args + env. Paste this into whichever client you're using; the paths differ per platform.

{
  "mcpServers": {
    "webscans": {
      "command": "webscans",
      "args": ["mcp"],
      "env": {
        "WEBSCANS_API_KEY": "ws_..."
      }
    }
  }
}

Prefer full paths for reliability. If webscans isn't on your client's PATH, use the absolute path: "command": "/usr/local/bin/webscans" (or wherever which webscans shows).

Claude Desktop

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

Paste the JSON above into that file (create if missing), restart Claude Desktop, and you should see WebScans in the tools menu.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "webscans": {
      "command": "webscans",
      "args": ["mcp"],
      "env": { "WEBSCANS_API_KEY": "ws_..." }
    }
  }
}

Or user-scoped with the CLI: claude mcp add webscans webscans mcp -e WEBSCANS_API_KEY=ws_...

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json in the project root. Same JSON shape.

Zed

Zed settings.json under context_servers. Same JSON, restart Zed.

Custom agents

Any framework that speaks MCP (LangGraph, LlamaIndex, Anthropic's own mcp Python SDK, OpenAI Agents SDK, etc.) can connect to a stdio server:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="webscans",
    args=["mcp"],
    env={"WEBSCANS_API_KEY": "ws_..."},
)
async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool("enrich_domain", {"domain": "stripe.com"})

Tools exposed to the model

Tool descriptions are written for LLMs — verbose, example-heavy, opinionated about when to use each. The model picks the right one from natural user intent.

Tool	Purpose	Example prompt that triggers it
`search_companies`	Keyword + filter search over 13.3M homepages	"find SaaS companies in California using HubSpot"
`count_search`	Cheap total-match count	"how many companies mention carbon accounting?"
`lookup_domain`	Full 178-field cached profile	"tell me about stripe.com"
`find_similar_companies`	FAISS lookalike discovery	"companies like Figma"
`enrich_domain`	Real-time enrichment cascade	"get me fresh data on acme.io"
`autocomplete`	As-you-type suggestions	"suggest domain names starting with stri"
`ai_search`	Natural-language wrapper around the whole toolkit	"do whatever you need — find me fintech in the UK"

search_companies

Args: query (str, required), mode (phrase|any|single, default phrase), tech, industry, country, tld, has, limit (default 25).

lookup_domain

Args: domain (str, required). Returns cached 178-field profile. Use enrich_domain if freshness matters.

find_similar_companies

Args: domain (str, required), limit (default 25). Returns competitors ranked by cosine similarity over gte-Qwen2-7B-instruct embeddings.

enrich_domain

Args: domain, wait_ms (default 800), force (default false). Runs the full cascade: cache → live+CC-WET race → Playwright → Bright Data. Sub-1s p95 for indexed domains.

autocomplete

Args: q, limit (default 6), mode ("domain" for domain-only suggestions).

ai_search

Args: message. Natural-language wrapper — delegates to Claude which picks the right tool. Useful for open-ended questions where the client isn't sure upfront which tool applies.

Environment variables

Var	Purpose
`WEBSCANS_API_KEY`	Required for authenticated tools + high rate limits
`WEBSCANS_BASE_URL`	Override for self-hosted / staging (default `https://webscans.com`)

Troubleshooting

"webscans: command not found" — Your MCP client isn't seeing the executable. Use the full path from which webscans.
Tools don't show up in Claude Desktop — Restart the app after editing the config. Check the client's log for JSON parse errors.
Every tool call returns 401 — WEBSCANS_API_KEY isn't reaching the process. Verify with env | grep WEBSCANS in the same shell that spawns the client.
Slow first call — Cold Python startup adds ~500ms. Subsequent calls are fast because the client + connection pool are cached in-process.

Still stuck? Open an issue.