Connect Retriever MCP to Cursor, Claude Desktop, and ChatGPT: The Complete Guide

Emma Guetta

Emma Guetta, co-founder of Retriever. I use these systems every day to sell it.

Before you dive in, a word about Retriever, the product this guide comes from. It's a go-to-market AI agent that builds qualified prospect lists from one prompt: you describe your ICP in plain English, the agent searches across 30+ data sources, qualifies every company against your criteria, and returns a ranked list with its reasoning visible. The guides in this section document the systems I use to sell it.

Build AI agents for lead generation in 5 minutes.Pick an idea, delegate once. Your agent finds the right companies and reaches out.Get started

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:

PlatformProtocol / TransportAuth MechanismConfiguration File / UIBest For
CursorHTTP / SSE or local stdioBearer Token API KeyCursor Settings > Features > MCP or .cursor/mcp.jsonDevelopers, GTM Engineers, automated script workflows
Claude DesktopRemote Streamable HTTPBearer Token API Key or OAuth 2.1claude_desktop_config.json or Settings > Customize > ConnectorsDeep interactive desktop analysis, executive research
ChatGPTRemote Streamable HTTPOAuth 2.1 (1-click) or Bearer TokenSettings > Developer Mode > ConnectorsWeb & 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:

  1. Sign in to your account at app.retriever.run.
  2. Click Settings in the left sidebar, then navigate to API Keys.
  3. Click Generate New Key.
  4. 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.

  1. Open Cursor.
  2. Open Settings:
    • macOS: Press Cmd + ,
    • Windows / Linux: Press Ctrl + ,
  3. In the sidebar, select Features, then scroll down to MCP Servers (or Tools & MCP depending on your Cursor version).
  4. Click the + Add New MCP Server button.
  5. Enter the following parameters:
    • Name: retriever
    • Type: http
    • URL: https://api.retriever.run/mcp
    • Headers:
      {
        "Authorization": "Bearer YOUR_RETRIEVER_API_KEY"
      }
      
  6. 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 + I on Mac, Ctrl + I on Windows). Click the tool selector icon at the bottom of the input. You should see retriever listed 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:

  1. Quit Claude: Cmd + Q on macOS (do not just click the red close circle), or right-click the Claude icon in the Windows system tray and select Quit.
  2. 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.

  1. Open connectors: Settings → Customize → Connectors (on Team and Enterprise, an owner adds it once from Organization settings → Connectors).
  2. Click +, then Add custom connector, and set Remote MCP server URL to https://api.retriever.run/mcp.
  3. Click Connect and authorize in the app.retriever.run window. No API key to copy: the connector uses your workspace credits.
  4. 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.json in 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:

  1. Quit Claude: Cmd + Q on macOS (do not just click the red close circle), or right-click the Claude icon in the Windows system tray and select Quit.
  2. 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

  1. Open ChatGPT on the web (chatgpt.com).
  2. Click your profile photo in the bottom-left corner and open Settings.
  3. In the settings modal, navigate to Security & login (or Connectors / Apps).
  4. Turn on the Developer Mode toggle.
  5. In the Connectors section, click Create connector (or Add app).
  6. Fill in the connection details:
    • Name: Retriever
    • Server URL: https://api.retriever.run/mcp
  7. Authentication:
    • OAuth 2.1 (Instant & Recommended): ChatGPT will automatically query Retriever's .well-known discovery endpoints. A pop-up window from app.retriever.run will 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.
  8. Click Save.

Using Retriever in ChatGPT

  1. Start a new chat in ChatGPT.
  2. In the message composer, click the + (plus) button on the left.
  3. Select Retriever from the list of available apps.
  4. 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:

  1. service_discover: The agent describes its intent (e.g. "find work email", "meta ads", "french company siren"). Retriever returns the matching canonical service name.
  2. service_inspect: The agent reads the exact schema, required parameters, and credit cost.
  3. 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:

  1. The model calls service_discover for company search signals.
  2. It queries Retriever's company database filtering by country, funding stage, and tech stack.
  3. It validates recent job postings to confirm active engineering hiring.
  4. 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:

  1. The model calls service_execute with findPersonAtCompany specifying the company domain (pennylane.com) and target seniority (VP / Head of).
  2. It executes findWorkEmail and findMobilePhone on the identified contact.
  3. 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:

  1. The model invokes retriever_research_start and service_execute for ad signals.
  2. It collects active advertising creative angles, recent leadership hires, and technographic signatures.
  3. 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:

  1. The model calls retriever_build_list_start.
  2. Retriever provisions a persistent table in your workspace and streams qualified leads into it.
  3. The model calls sequence_create to 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 as Authorization: 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 credits tool 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"):
    1. Confirm claude_desktop_config.json is valid JSON and the Authorization header is Bearer ret_sk_... with no stray spaces.
    2. Fully quit Claude (Cmd + Q on macOS) rather than minimizing the window, then relaunch.
  • If you used a custom OAuth connector:
    1. In Settings → Customize → Connectors, check that Retriever shows as connected. If it shows Connect, complete the login window.
    2. In the chat, click + → Connectors and switch Retriever on (per conversation).
    3. On a Free plan, only one custom connector is allowed, so remove the other first.
  • If you used the mcp-remote stdio bridge instead:
    1. Verify that Node.js (v18 or newer) is installed by running node -v in your terminal.
    2. Ensure you didn't leave a trailing comma or syntax error in claude_desktop_config.json.
    3. Check that the header is written as "Authorization:${RETRIEVER_AUTH}" with no space around the :, and the Bearer prefix kept in env.
    4. Ensure you completely quit Claude (Cmd + Q on macOS) rather than simply minimizing the window.

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 your ret_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.

Emma Guetta

About me

I'm Emma Guetta, co-founder of Retriever, a go-to-market AI agent that builds qualified prospect lists from a prompt (think Claude Code for go-to-market). Same principle as this guide: you describe what you want, an agent does the repetitive work, and you keep control of the result. Questions or feedback: find me on LinkedIn.