The guide
A guide by Emma Guetta, co-founder of Retriever
Why give your AI tools live B2B intelligence?
Most AI assistants are brilliant at writing code and answering general questions, but completely blind when it comes to the live market.
If you ask Cursor, Claude Desktop, or ChatGPT:
- "Which European B2B SaaS companies raised Series A in the last 6 months and are currently expanding their sales team?"
- "Find the verified work email and mobile phone for the VP Sales at Pigment."
- "Check what advertising campaigns Pennylane is running on Meta right now."
The model will either hallucinate convincing-sounding names, quote obsolete information from its pre-training cutoff, or tell you to go look it up on LinkedIn manually.
The Model Context Protocol (MCP), originally created by Anthropic and rapidly adopted by Cursor and OpenAI, solves this by giving AI models a standardized way to call external tools and retrieve structured context in real time.
By connecting Retriever's MCP Server to your AI environment, you give your models direct programmatic access to:
- 35M+ indexed company profiles across Europe and the US,
- Live hiring intent extracted from global job boards,
- Fresh website and tech-stack crawling signals,
- Verified contact intelligence (work emails, direct mobile numbers, LinkedIn URLs),
- Autonomous prospecting agents that can research markets, score ICP fit from 0 to 100 with cited evidence, and build full lead tables.
This guide walks you through the exact setup for Cursor, Claude Desktop, and ChatGPT, followed by real-world workflows and troubleshooting advice.
The three clients at a glance
Before configuring your tools, here is how each platform connects to Retriever:
| Platform | Protocol / Transport | Auth Mechanism | Configuration File / UI | Best For |
|---|---|---|---|---|
| Cursor | HTTP / SSE or local stdio | Bearer Token API Key | Cursor Settings > Features > MCP or .cursor/mcp.json | Developers, GTM Engineers, automated script workflows |
| Claude Desktop | Remote Streamable HTTP | Bearer Token API Key or OAuth 2.1 | claude_desktop_config.json or Settings > Customize > Connectors | Deep interactive desktop analysis, executive research |
| ChatGPT | Remote Streamable HTTP | OAuth 2.1 (1-click) or Bearer Token | Settings > Developer Mode > Connectors | Web & mobile usage, sales reps, non-technical team members |
Step 0: Get your Retriever API key
All three platforms connect to the same underlying Retriever backend. You will need an active API key:
- Sign in to your account at app.retriever.run.
- Click Settings in the left sidebar, then navigate to API Keys.
- Click Generate New Key.
- Copy your key (it starts with
ret_sk_...). Keep it safe: it gives access to your credit balance.
1. Setting up Retriever in Cursor
Cursor is one of the most powerful hosts for MCP because its AI agent (Cursor Composer) can query Retriever tools while simultaneously writing code, populating CSV files, or scaffolding internal scrapers.
Cursor supports two setup methods: through its graphical settings interface, or through a project-scoped .cursor/mcp.json file.
Method A: Via Cursor Settings (Fastest & Global)
This method makes Retriever available across all your Cursor windows and projects.
- Open Cursor.
- Open Settings:
- macOS: Press
Cmd + , - Windows / Linux: Press
Ctrl + ,
- macOS: Press
- In the sidebar, select Features, then scroll down to MCP Servers (or Tools & MCP depending on your Cursor version).
- Click the + Add New MCP Server button.
- Enter the following parameters:
- Name:
retriever - Type:
http - URL:
https://api.retriever.run/mcp - Headers:
{ "Authorization": "Bearer YOUR_RETRIEVER_API_KEY" }
- Name:
- Click Save.
Within a few seconds, a green status circle will appear next to retriever, indicating that Cursor has connected and registered all tools (service_discover, service_execute, retriever_research_start, table_*, etc.).
Method B: Via .cursor/mcp.json (Project-Scoped)
If you work in a team repository and want everyone on the team to share the same MCP configuration, create a .cursor/mcp.json file at the root of your project:
{
"mcpServers": {
"retriever": {
"type": "http",
"url": "https://api.retriever.run/mcp",
"headers": {
"Authorization": "Bearer YOUR_RETRIEVER_API_KEY"
}
}
}
}
Bridging over local stdio in Cursor
Older Cursor builds only accept MCP servers launched as a local process. You can still reach the same hosted endpoint by putting mcp-remote in front of it, which relays stdio to HTTPS (Node.js 18+ required):
{
"mcpServers": {
"retriever": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.retriever.run/mcp",
"--header",
"Authorization:${RETRIEVER_AUTH}"
],
"env": {
"RETRIEVER_AUTH": "Bearer YOUR_RETRIEVER_API_KEY"
}
}
}
}
The header value is passed through env on purpose: Cursor does not escape spaces inside args, so "Authorization: Bearer ..." written inline gets mangled. Note there is no space around the : in "Authorization:${RETRIEVER_AUTH}".
Verification in Cursor:
Open Composer (Cmd + Ion Mac,Ctrl + Ion Windows). Click the tool selector icon at the bottom of the input. You should seeretrieverlisted with all available capabilities.
2. Setting up Retriever in Claude Desktop
Retriever's MCP server is hosted at https://api.retriever.run/mcp. Claude Desktop can reach it over remote HTTP with your ret_sk_ API key (the same JSON shape as Cursor) or through a custom connector with OAuth 2.1. There is no npm package to install (@agentic-list-building/mcp-server is not published).
Method A: claude_desktop_config.json with HTTP (API key)
Open your Claude Desktop configuration file:
- On macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - On Windows:
%APPDATA%\Claude\claude_desktop_config.json
Shortcut: In Claude Desktop, click Claude in the top menu → Settings → Developer → click Edit Config.
If the file is empty, paste the following JSON. If it already contains other MCP servers, add retriever inside the mcpServers object:
{
"mcpServers": {
"retriever": {
"type": "http",
"url": "https://api.retriever.run/mcp",
"headers": {
"Authorization": "Bearer YOUR_RETRIEVER_API_KEY"
}
}
}
}
Replace YOUR_RETRIEVER_API_KEY with your actual key starting with ret_sk_, keeping the Bearer prefix.
Then restart Claude completely. Saving the file is not enough, because Claude Desktop only initializes MCP servers on boot:
- Quit Claude:
Cmd + Qon macOS (do not just click the red close circle), or right-click the Claude icon in the Windows system tray and select Quit. - Relaunch Claude Desktop.
Within a few seconds, the hammer icon in the chat should list Retriever tools (credits, service_discover, service_execute, retriever_research_start, table_get_rows, sequence_list, and others).
Method B: Custom connector (OAuth 2.1)
Custom connectors are available on Free, Pro, Max, Team and Enterprise plans, in Claude Desktop and on the web. Free plans are limited to one custom connector.
- Open connectors: Settings → Customize → Connectors (on Team and Enterprise, an owner adds it once from Organization settings → Connectors).
- Click +, then Add custom connector, and set Remote MCP server URL to
https://api.retriever.run/mcp. - Click Connect and authorize in the
app.retriever.runwindow. No API key to copy: the connector uses your workspace credits. - In a chat, click + → Connectors and switch Retriever on for that conversation.
Alternative: bridging over local stdio
If your organization disables custom connectors, Claude Desktop can reach the same hosted server through mcp-remote, which relays stdio to HTTPS. This path needs Node.js 18 or newer.
Open your Claude Desktop configuration file:
- On macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - On Windows:
%APPDATA%\Claude\claude_desktop_config.json
Shortcut: In Claude Desktop, click Claude in the top menu → Settings → Developer → click Edit Config. This will automatically open the folder containing
claude_desktop_config.jsonin Finder or File Explorer.
If the file is empty, paste the following JSON. If it already contains other MCP servers, add retriever inside the mcpServers object:
{
"mcpServers": {
"retriever": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.retriever.run/mcp",
"--header",
"Authorization:${RETRIEVER_AUTH}"
],
"env": {
"RETRIEVER_AUTH": "Bearer YOUR_RETRIEVER_API_KEY"
}
}
}
}
Replace YOUR_RETRIEVER_API_KEY with your actual key starting with ret_sk_, keeping the Bearer prefix.
The header is passed through env rather than written inline in args: Claude Desktop on Windows does not escape spaces inside args, which mangles the value. Note there is no space around the : in "Authorization:${RETRIEVER_AUTH}".
Then restart Claude completely. Saving the file is not enough, because Claude Desktop only initializes local MCP servers on boot:
- Quit Claude:
Cmd + Qon macOS (do not just click the red close circle), or right-click the Claude icon in the Windows system tray and select Quit. - Relaunch Claude Desktop.
A small hammer icon appears near the prompt box. Click it to list the registered Retriever tools.
3. Setting up Retriever in ChatGPT
ChatGPT operates entirely in OpenAI's cloud and requires a remote HTTPS endpoint that supports the Streamable HTTP MCP specification, the same endpoint Claude Desktop connects to.
Retriever's public server at https://api.retriever.run/mcp implements the official OAuth 2.1 protocol with dynamic client registration and PKCE S256 (/.well-known/oauth-authorization-server). This allows ChatGPT to link directly to your Retriever workspace without even requiring you to copy-paste a token.
Prerequisites
- A paid ChatGPT plan: ChatGPT Plus, Team, Pro, or Enterprise.
- Access to Developer Mode or Connectors / Apps in ChatGPT.
Step-by-step Setup
- Open ChatGPT on the web (chatgpt.com).
- Click your profile photo in the bottom-left corner and open Settings.
- In the settings modal, navigate to Security & login (or Connectors / Apps).
- Turn on the Developer Mode toggle.
- In the Connectors section, click Create connector (or Add app).
- Fill in the connection details:
- Name:
Retriever - Server URL:
https://api.retriever.run/mcp
- Name:
- Authentication:
- OAuth 2.1 (Instant & Recommended): ChatGPT will automatically query Retriever's
.well-knowndiscovery endpoints. A pop-up window fromapp.retriever.runwill ask you to log in and authorize the connection. Click Allow. - Manual Bearer Token: If your organization requires static credentials, choose Bearer authentication and paste your Retriever API key.
- OAuth 2.1 (Instant & Recommended): ChatGPT will automatically query Retriever's
- Click Save.
Using Retriever in ChatGPT
- Start a new chat in ChatGPT.
- In the message composer, click the + (plus) button on the left.
- Select Retriever from the list of available apps.
- You can now prompt ChatGPT to run live market lookups and company research directly in the conversation.
The Retriever tools reference
Once connected, your AI assistant has access to four core capability families:
Host Agent (Cursor / Claude / ChatGPT)
│
├── 1. Atomic Services ───────> service_discover / service_inspect / service_execute
│ (Emails, Direct Phones, Ads, Tech Stack, Jobs)
│
├── 2. Autonomous Research ───> retriever_research_start / retriever_research_get
│ (Live web crawling, evidence synthesis, dossier)
│
├── 3. List Building & ICP ───> retriever_build_list_start / table_get_rows
│ (Calibrate sources, evaluate fit score 0–100)
│
└── 4. Outreach Sequences ───> sequence_create / sequence_enroll_leads / inbox_list
(Multi-step LinkedIn & Email campaigns)
1. Atomic Services (service_*)
Retriever packages dozens of B2B data providers and live crawlers into standardized atomic capabilities called Services. The agent follows a disciplined 3-step loop:
service_discover: The agent describes its intent (e.g."find work email","meta ads","french company siren"). Retriever returns the matching canonical service name.service_inspect: The agent reads the exact schema, required parameters, and credit cost.service_execute: The agent executes the service and receives clean JSON with source evidence.
2. Autonomous Research (retriever_research_*)
For questions that require checking multiple sources across the web (e.g. analyzing a competitor's pricing tiers or investigating whether a company has a dedicated security team), retriever_research_start spins up an autonomous research sub-agent. The agent crawls sites, verifies claims, and returns a cited dossier.
3. List Building & ICP (retriever_build_list_* & table_*)
Instead of dumping raw lists into the chat, the agent can create structured tables in your Retriever workspace. Each lead is evaluated against your custom Ideal Customer Profile (ICP), receiving a fit score between 0 and 100 along with explicit reasoning.
4. Outreach Sequences (sequence_* & inbox_*)
Your agent can draft multi-channel outreach campaigns (combining automated LinkedIn profile visits, connection requests, and personalized emails), enroll leads from tables, and monitor incoming replies from the shared inbox.
4 Real-world workflows to try
Here are four prompts you can paste directly into Cursor, Claude Desktop, or ChatGPT once your MCP is connected.
Workflow 1: Account discovery with precise ICP filtering
Prompt:
"Using Retriever, find 5 B2B SaaS companies headquartered in France that have raised Series A or B, use Stripe or Chargebee for billing, and are currently hiring software engineers. For each, give me their domain, ICP score, and the proof."
What happens:
- The model calls
service_discoverfor company search signals. - It queries Retriever's company database filtering by country, funding stage, and tech stack.
- It validates recent job postings to confirm active engineering hiring.
- It outputs a clean comparison table with links to original sources.
Workflow 2: Finding verified decision-maker contacts
Prompt:
"I need to reach out to Pennylane about their automated accounting integration. Use Retriever to find their Head of Sales or VP Sales, and return their verified work email, direct mobile phone number, and LinkedIn URL."
What happens:
- The model calls
service_executewithfindPersonAtCompanyspecifying the company domain (pennylane.com) and target seniority (VP / Head of). - It executes
findWorkEmailandfindMobilePhoneon the identified contact. - It returns the contact's direct details along with verification status (e.g., SMTP deliverability check).
Workflow 3: Generating an account briefing dossier before a sales call
Prompt:
"I have a discovery call in 30 minutes with Dataiku. Use Retriever to pull a full intelligence dossier: recent funding rounds, open roles in their revenue team, tech stack detected on their marketing site, and active Meta ad copy."
What happens:
- The model invokes
retriever_research_startandservice_executefor ad signals. - It collects active advertising creative angles, recent leadership hires, and technographic signatures.
- It produces an executive 1-page pre-call brief highlighting pain points you can address during the call.
Workflow 4: Autonomous list building and sequence drafting
Prompt:
"Start a list-building mission on Retriever called 'FinTech Growth 2026'. Target 20 European FinTech scale-ups that hired a new CMO in the last 90 days. Once the table is ready, draft a 3-step outreach sequence tailored to each company's recent announcements."
What happens:
- The model calls
retriever_build_list_start. - Retriever provisions a persistent table in your workspace and streams qualified leads into it.
- The model calls
sequence_createto set up a personalized 3-step cadence (Day 1: LinkedIn connection with custom context; Day 3: Email referencing CMO hire; Day 7: Follow-up case study).
Troubleshooting & FAQ
401 Unauthorized or invalid_token
- Cause: The API key is missing, expired, or contains whitespace.
- Fix: Check that your key starts with
ret_sk_and that the header is formatted asAuthorization: Bearer ret_sk_.... If you connected through the Claude or ChatGPT connector, no key is involved: disconnect and reconnect the connector to refresh the OAuth grant.
402 Payment Required or insufficient_credits
- Cause: Your account balance has reached 0 credits.
- Fix: Run the
creditstool in your agent to inspect your wallet balance. You can add credits anytime from app.retriever.run/settings.
Retriever tools do not appear in Claude Desktop
- If you used the HTTP config (
type: "http"):- Confirm
claude_desktop_config.jsonis valid JSON and theAuthorizationheader isBearer ret_sk_...with no stray spaces. - Fully quit Claude (
Cmd + Qon macOS) rather than minimizing the window, then relaunch.
- Confirm
- If you used a custom OAuth connector:
- In Settings → Customize → Connectors, check that Retriever shows as connected. If it shows Connect, complete the login window.
- In the chat, click + → Connectors and switch Retriever on (per conversation).
- On a Free plan, only one custom connector is allowed, so remove the other first.
- If you used the
mcp-remotestdio bridge instead:- Verify that Node.js (v18 or newer) is installed by running
node -vin your terminal. - Ensure you didn't leave a trailing comma or syntax error in
claude_desktop_config.json. - Check that the header is written as
"Authorization:${RETRIEVER_AUTH}"with no space around the:, and theBearerprefix kept inenv. - Ensure you completely quit Claude (
Cmd + Qon macOS) rather than simply minimizing the window.
- Verify that Node.js (v18 or newer) is installed by running
ChatGPT connector fails to authenticate
- Cause: Browser cookie blocking or stale redirect.
- Fix: Ensure third-party cookies are allowed for
retriever.run. If the pop-up consent window fails to complete, select Bearer Token authentication in ChatGPT settings and paste yourret_sk_key directly.
Summary & Next Steps
Connecting Retriever via MCP transforms your AI assistants from text generators into autonomous revenue team members:
- Cursor becomes an automated lead-generation terminal.
- Claude Desktop acts as an on-demand market intelligence analyst.
- ChatGPT allows your entire sales and marketing team to query real B2B data on the fly.
To get started, generate your key at app.retriever.run and copy the configuration snippet for your assistant.
