--- updatedAt: 2026-10-15T09:08:36.000Z agentTools: projectIndex: https://docs.cognism.com/llms.txt --- # Cognism MCP server Connect Claude, ChatGPT, Cursor and other MCP-compatible AI assistants to Cognism data and search, count and reveal in plain language. The Cognism MCP server lets an AI assistant work with Cognism data on your behalf. Connect it once, sign in with your Cognism account, and you can ask your assistant to find companies, build contact lists, size an audience or reveal contact details — without leaving the conversation. It exposes the same data and rules as the [Cognism API](/docs/getting-started): your subscription, compliance settings, search-token allowance and credit balance all apply. [MCP (Model Context Protocol)](https://modelcontextprotocol.io) is an open standard that lets AI clients call external tools. The Cognism server is a **remote MCP server** using Streamable HTTP transport and OAuth 2.0 sign-in, so it works with any client that supports those two things — no local installation required. ## Server details | | | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Server URL | `https://mcp.cognism.com/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth 2.0 — sign in with your Cognism credentials (or your organisation's SSO) in the browser when your client prompts you | | Access scope | Your own Cognism user. The assistant can only see and do what you can in the Cognism platform | | Cost | Search tokens per record returned; credits per contact revealed — the same metering as the API. See [Credits and search tokens](/docs/credits-and-search-tokens) | ## Before you begin * An active Cognism account. * Credits available if you intend to reveal contact details. * An MCP client that supports Streamable HTTP and OAuth (all clients below do). * A browser for the one-time sign-in. Data retrieved through the MCP server may not be used to train AI models. Turn model training off in your AI client or account settings before connecting, and check your vendor's data-retention terms — contact details revealed into an assistant are stored in that conversation. ## Connect your client ### Claude (claude.ai, Claude Desktop, Cowork) 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Name it `Cognism` and paste the server URL [`https://mcp.cognism.com/mcp`](https://mcp.cognism.com/mcp). 3. Click **Add**, then **Connect**. Sign in with your Cognism credentials when the browser opens. The Cognism tools appear in the tools menu of new chats. Enable the connector per conversation if your workspace requires it. ### Claude Code ```bash claude mcp add --transport http cognism https://mcp.cognism.com/mcp ``` Then run `/mcp` inside Claude Code, select **cognism** and choose **Authenticate** to complete the browser sign-in. ### ChatGPT 1. Open **Settings → Connectors** (developer mode must be enabled by your workspace admin) and choose **Create**. 2. Name it `Cognism`, paste [`https://mcp.cognism.com/mcp`](https://mcp.cognism.com/mcp) as the MCP server URL, and select **OAuth** authentication. 3. Save, then sign in with your Cognism credentials when prompted. ### OpenAI Codex ```bash codex mcp add cognism --url https://mcp.cognism.com/mcp codex mcp login cognism ``` ### Cursor Add the server to `~/.cursor/mcp.json` (or via **Settings → MCP → Add new server**), then restart Cursor and complete the sign-in when prompted: ```json { "mcpServers": { "cognism": { "url": "https://mcp.cognism.com/mcp" } } } ``` ### VS Code (GitHub Copilot) Create `.vscode/mcp.json` in your workspace, then run **MCP: List Servers** from the Command Palette, start `cognism` and complete the sign-in: ```json { "servers": { "cognism": { "type": "http", "url": "https://mcp.cognism.com/mcp" } } } ``` ### Any other MCP client Point the client at [`https://mcp.cognism.com/mcp`](https://mcp.cognism.com/mcp) with Streamable HTTP transport and OAuth 2.0 authentication. Clients that only support API-key or stdio servers are not supported. ## Available tools Once connected, your assistant can call these tools. They map one-to-one onto the [API endpoints](/docs/endpoints) and accept the same filters as the [API reference](/reference/searchpersons). | Tool | What it does | Cost | | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- | | `company_search` | Search companies by industry, location, headcount, revenue, technologies, events and intent. Optional `view` segments add locations, industries, technologies and events. | 1 search token per record | | `company_count` | Count the companies matching a filter without returning them. | Free | | `people_search` | Search people by job title, seniority, department, skills and location, combined with any company filter. `view: contacts` returns email and phone numbers. | 1 search token per record; **1 credit per record with **`contacts` | | `people_count` | Count the people matching a filter without returning them. | Free | | `dictionary_industries` | Resolve industry names and the three-level industry taxonomy. | Free | | `dictionary_industry_codes` | Look up SIC, NAICS and ISIC codes. | Free | | `dictionary_countries` | Resolve exact country names (filters need `"United Kingdom"`, not `"UK"`). | Free | | `dictionary_regions` | List regions (Africa, Americas, Asia, Europe, Oceania). | Free | | `dictionary_departments` | List departments. | Free | | `dictionary_seniorities` | List seniority levels. | Free | | `dictionary_technologies` | Resolve technology names. | Free | | `dictionary_intent_topics` | Intent topic catalogue (empty in the current version). | Free | | `account_intent_topics` | The intent topics selected for your account. | Free | | `account_compliance_settings` | Your account's do-not-call masking and geo-restriction settings. | Free | | `account_personalization_settings` | Your account's selected intent topics and watched technologies. | Free | ## What to ask The assistant chooses tools from your request; you do not need to name them. Good prompts state the audience, the geography and what you want back. > Find UK-headquartered software companies with 200–1,000 employees and tell me how many there are. > List 20 Marketing VPs at those companies. Don't reveal contact details yet. > Reveal emails and mobile numbers for the first five. > Which of my target accounts have hired a Head of Sales in the last 90 days? > How many credits and search tokens will that use? A well-behaved assistant follows the pattern **dictionary → count → search → reveal**: it resolves your wording to exact values, checks the size of the result set, retrieves records without contact details, and asks before spending credits on a reveal. If your assistant reveals contacts without asking, tell it not to — the instruction persists for the conversation. ## Cost and limits | | | | :------------ | :---------------------------------------------------------------------------------------------------------------------- | | Search tokens | One per record returned by `company_search` or `people_search`. Counts and dictionaries are free. | | Credits | One per person record returned by `people_search` with the `contacts` segment. Nothing else consumes credits. | | Rate limits | The API's per-account limits apply — 500 requests per minute per operation class. See [Rate limits](/docs/rate-limits). | | Page size | Up to 100 records per tool call. Larger asks are paged; each page spends tokens. | Balances and usage are visible in the Cognism platform. If your allowance runs out the assistant receives the same `402` / `429` errors as an API client and should tell you to wait or contact your account team. ## Compliance Compliance rules are enforced by the server, not by the assistant, and cannot be bypassed by rephrasing a prompt: * Phone numbers for people in your account's **do-not-call countries** are masked. * Records in **geo-restricted countries** are excluded from results. * Check what applies to you with `account_compliance_settings` or `GET /settings/compliance`. ## Troubleshooting | Symptom | Likely cause | What to do | | :----------------------------------------------------------------------------------- | :----------------------------------------------------- | :---------------------------------------------------------------------------- | | Client says the server was not found (`404`) or is not enabled (`403`) after sign-in | MCP access is not yet enabled for your account or user | Contact your Cognism account team | | Sign-in page appears but your credentials are rejected | Your user has not been provisioned for API/MCP sign-in | Contact your Cognism administrator | | Tools connect but searches return nothing | Filter values are not exact dictionary values | Ask the assistant to look up the industry, country or seniority first | | "Insufficient budget" / `402` | Search tokens exhausted for the billing period | Wait for the reset shown in the message, or contact your account team | | Assistant reveals contacts you did not ask for | Assistant skipped the confirmation step | Tell it to ask before revealing contacts; revoke and reconnect if it persists | To disconnect, remove the connector in your client's settings. ## Security notes * You sign in with your own Cognism account; there is no shared API key to store or rotate. Never paste API client secrets into an AI assistant. * Treat instructions embedded in web pages or documents the assistant reads as untrusted — an assistant acting on them could spend credits. Keep confirm-before-reveal behaviour on. * Only install the Cognism connector from the URL above or from the official listings in your client's marketplace.