For AI agents

The FirmLens MCP server

Give your AI agent the FirmLens directories. Over the Model Context Protocol, Claude or any other MCP client can search the companies, filter them by field and read their crawled websites, all from inside a conversation.

Server address

Point your client at the Streamable HTTP endpoint:

https://mcp.firmlens.io/mcp

Clients that only speak the older SSE transport can connect to https://mcp.firmlens.io/sse instead.

Pass your API key as a header

The server does not store any keys. Your client sends your FirmLens API key with every request, in the x-api-key header, and the server passes it on to the FirmLens API. A request without a key is refused with 401 Unauthorized.

x-api-key: YOUR_FIRMLENS_API_KEY

If your client can only send a bearer token, that works too:

Authorization: Bearer YOUR_FIRMLENS_API_KEY

Your FirmLens API key will be issued through World Wide Web Data when you register a FirmLens account.

Treat the key like a password. Keep it in your client's configuration and don't paste it into a prompt or a shared file.

Connect your agent

Claude Code adds the server and its header in one command:

claude mcp add --transport http firmlens https://mcp.firmlens.io/mcp \
  --header "x-api-key: YOUR_FIRMLENS_API_KEY"

Other clients that read a JSON configuration take an entry like this one. Where the server list lives, and what its keys are called, differs a little between clients, so check yours:

{
  "mcpServers": {
    "firmlens": {
      "url": "https://mcp.firmlens.io/mcp",
      "headers": {
        "x-api-key": "YOUR_FIRMLENS_API_KEY"
      }
    }
  }
}

Once connected, ask your agent something like “Find solar installers in Germany that do EPC work”. It starts with list_directories to see what it can search.

Tools

Directory searches cover the renewable energy and car dealership directories. Each result carries a refId your agent can pass to web_cache_search_match to read that company's crawled pages.

Directory tools
Tool	What it does	Credits
list_directories	Lists the directories you can search	Free
get_search_fields	Lists the searchable fields of a directory	Free
get_stats	Your remaining quota and call counts	Free
search	Free-text search across every field of a directory	10
search_match	Search specific fields, optionally as an exact match	10
search_match_multiple	A different query per field, all of which must match	10
search_fields_exists	Companies that have data in the given fields	10

The web tools work on any crawled website, not just directory companies:

Web data tools
Tool	What it does	Credits
get_web_info	Resolved URL, IP addresses and last crawl date of a website	1
get_web_data	Data extracted from a website, including schema.org data	1
web_cache_search	Full-text search across crawled pages	1
web_cache_search_match	Search one page field; with refId, a company's crawled pages	1

Credits and limits

Credits are charged to your API key per call, not per result. Directory searches return up to 100 companies a call. Your agent can check your remaining quota for free with get_stats.

Each key may make bursts of up to 60 requests, refilled at 2 per second. Beyond that the server answers 429 Too Many Requests until the allowance refills.

Questions, or need a higher limit? Get in touch.