FirmLens

npx add-mcp 'https://mcp.firmlens.io/mcp'

The FirmLens MCP server

Ask Claude to “find solar installers in Germany that do EPC work” and get real companies back, with their projects and details. The FirmLens MCP server connects Claude, ChatGPT or any other MCP client to our directories, so your agent can search companies, filter them by field and read their crawled websites 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.

Sign in or use an API key

There are two ways to connect. Both use your free FirmLens account and its credits.

Sign in with your FirmLens account. Clients that support MCP sign-in, such as Claude and ChatGPT, only need the server address. When you add it, they open a FirmLens login page where you sign in with your usual email and password and approve the connection. There is nothing to copy or paste, and your API key never leaves FirmLens. Your account needs a verified email address.

Every app you connect this way is listed under Connected apps on your account page. Disconnect one there and it loses access straight away. Resetting your password disconnects them all.

Or pass your API key as a header. For Claude Code, your own agents and any client without sign-in, send your FirmLens API key with every request in the x-api-key header. The server does not store it; it passes it on to the FirmLens API.

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

Every verified FirmLens account comes with an API key. Find yours on your account page; no account yet? Create one for free.

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. A request with neither a sign-in nor a key is refused with 401 Unauthorized.

Connect your agent

Claude (claude.ai and the desktop app): open Settings, then Connectors, and choose Add custom connector. Enter https://mcp.firmlens.io/mcp and sign in with your FirmLens account when asked.

ChatGPT: open Settings, then Apps & Connectors, and under Advanced settings turn on Developer mode. Back in Apps & Connectors, choose Create, name the connector FirmLens, enter https://mcp.firmlens.io/mcp as the server URL and choose OAuth as the authentication. ChatGPT then sends you to FirmLens to sign in and approve. Developer mode depends on your ChatGPT plan, and menu names can differ slightly between ChatGPT versions.

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"

OpenAI Agents SDK and Responses API: the hosted MCP tool connects with your API key in a header. In Python:

from agents import Agent, HostedMCPTool

firmlens = HostedMCPTool(tool_config={
    "type": "mcp",
    "server_label": "firmlens",
    "server_url": "https://mcp.firmlens.io/mcp",
    "headers": {"x-api-key": "YOUR_FIRMLENS_API_KEY"},
    "require_approval": "never",
})

agent = Agent(name="Researcher", tools=[firmlens])

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. If your client supports MCP sign-in, leave out the headers and it will ask you to log in instead:

{
  "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, car dealership and cybersecurity directories. Each result carries a refId your agent can pass to web_cache_search_match to read that company's crawled pages.

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	1 per result
search_match	Search specific fields, optionally as an exact match	1 per result
search_match_multiple	A different query per field, all of which must match	1 per result
search_fields_exists	Companies that have data in the given fields	1 per result

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

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 FirmLens account, whether you connect by signing in or with your API key. Directory searches cost 1 credit per company returned, so a page of 3 companies costs 3 credits and a page of 100 costs 100. A search returns up to 100 companies, and your remaining quota must cover the page size you ask for. Web data tools cost 1 credit per call. Your agent can check your remaining quota for free with get_stats.

Running low? Top up on your account page. Credits are a one-off card payment through Stripe, with VAT added at checkout where it applies. They are added to your balance within a minute of paying and don't expire.

Each key or signed-in account 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.