POST {RETRIEVER_API_URL}/mcp). Names and descriptions match the runtime contract; exact input schemas are returned by tools/list when you connect.
For Cursor or Claude Desktop setup, see Model Context Protocol (MCP).
Account
Public services (level 1)
Resources:
retriever://skills/retriever-services (the discover → inspect → execute loop), retriever://skills/retriever-workspace (list-building runs and tables), retriever://skills/retriever-go (one question, no table).
service_discover filter categories: contacts, companies, jobs, web, social, ads, generate.
List-building (agent runs)
REST equivalent:
POST /v1/runs, GET /v1/runs, GET /v1/runs/{id}, POST /v1/runs/{id}/cancel. See New conversation or follow-up?.
These runs share your organization’s run slots with the API (5 by default). While they are all taken, a new run stays queued and starts on its own when one ends: do not start it again, a second run is billed. retriever_build_list_get returns started_at (null while queued) and queue, which says why the run waits. See Runs per organization.
Autonomous research (Go)
One question, one answer in the format you give, no table. The Go agent searches the web and can call every Retriever service (LinkedIn and Sales Navigator people search, company data, emails, phones); each service it calls is billed at its price. To build a list, useretriever_build_list_start.
Workspaces
A workspace holds the tables of a list. Itsid is the workspace_id that table_list, table_create, and retriever_build_list_start accept.
Typical flow for a new list:
workspace_list to reuse a workspace, else workspace_create, then table_create with its id as workspace_id.
Tables
Columns hidden in the app are left out.
include_hidden: true on table_list, table_get and table_get_rows returns them (live tables only): table_list and table_get flag them hidden: true, and table_get_rows includes their values.
To export a table as a file, the user exports it from the app (app_url). Over the API, POST /v1/runs/{id}/exports exports only the output tables of a completed run started with output: { "type": "tables", ... } (output_tables on retriever_build_list_start).
Exclusions
The lists belong to the whole organization. They filter what sources bring into tables (an excluded company also drops the people a people search finds there), not Go, direct service calls, contacts found row by row in a table, rows the agent writes itself from a service call, or lists imported into a table.
See Exclusions.
Scheduled runs
A scheduled run repeats a list-building mission on a cadence, in one workspace. Each execution spends the organization’s credits.
There is no webhook: read
scheduled_run_list_runs until the execution is over, then read the workspace’s tables with table_list and table_get_rows. Rows have no creation date. To find new rows, compare their ids with the ids already read. See Scheduled runs.
Plays
A play finds leads on a cadence, qualifies them, and contacts one person per account through its sequence. Each run spends the organization’s credits. The tools call/v1/plays; see Plays.
Follow a launched play’s runs with
scheduled_run_list_runs on its schedule_id.
Problem reports
The agent calls it on its own when it meets such a fault.
expected and actual are written by the agent and can quote the request it was working on.
Sequences (outreach)
The outreach tools (sequences, senders, shared inbox) are a tool set of their own. The hosted server lists them when the organization has a sender or a sequence. To choose yourself, set Settings → MCP Integration to On or Off, or add?tools=outreach or ?tools=none to the MCP URL. Over stdio, set RETRIEVER_MCP_TOOLS=outreach.
Step kinds and timing
A step is one ofinvite, message, email, visit_profile or like_posts. There is no separate wait step: each step carries its own delayDays/delayHours, the wait after the previous step. The first step goes startDelayDays/startDelayHours (sequence settings, 0 by default) after the enrollment, or after the activation for leads staged on a draft; its own delay is not used. The legacy delay and wait_for_event kinds are still accepted and converted: a leading delay becomes the start delay, a later one is added to the next step’s own delay, and a wait after an invitation becomes that invitation’s setting below. A legacy wait_for_event sent without ifNotAccepted becomes ifNotAccepted: "stop" (its old default), while a new invite defaults to "continue".
Waiting for an invitation to be accepted
After aninvite step, every following step, emails included, waits for the invitation to be accepted. A lead already connected does not wait. The invite step sets how long: maxWaitDays (1 to 30, default 7), counted from when the invitation was sent. An acceptance moves the lead on, and the next step’s own delay counts from the acceptance. At the deadline, ifNotAccepted: "continue" (the default) skips the remaining LinkedIn steps and goes on with the email steps; a lead with no email address, or a sequence with no email sender, stops there. ifNotAccepted: "stop" ends the lead.
Enrollment
- Leads without LinkedIn. In a sequence with LinkedIn and email steps, a lead with an email address but no LinkedIn URL is enrolled: it skips every LinkedIn step, gets its first email as soon as the sequence starts for it (after the start delay, if any), then the next emails after their own delays. The result counts these leads in
emailOnlyCount. A lead that lacks the contact data of the first step it would get is skipped with the reasonmissing_required_channel(for example no email in a sequence that starts with an email, even with a LinkedIn URL); put the invitation first or find the emails. - Leads in other sequences. Behaviour change: omitting
duplicatesnow meansrunning_elsewhere, so a lead still running in another sequence is skipped where it used to be enrolled; sendduplicates: "allow"to keep the old behaviour.duplicatesdecides what happens to a lead already in another sequence of the organization.running_elsewhere(the default) skips the leads still running in an active or paused sequence (reasonrunning_in_another_sequence); a lead whose other sequence is finished can be enrolled again.any_sequenceskips the leads another sequence has contacted or is contacting (reasonin_another_sequence); leads only staged on a draft are not counted, for either rule.allowenrolls them anyway, andalsoRunningElsewherecounts the enrolled leads also running in another sequence. On a draft sequence, the choice is kept and applied again when the sequence is activated. - Senders. A lead is skipped with
no_sender_availableonly when the sequence has no active sender on the channel it starts on. A sender whose daily quota is spent still takes leads: their sends wait for its next quota window.
LinkedIn messages in several parts
A LinkedInmessage step with splitMessage: true sends each paragraph of its text (separated by a blank line) as its own message, a few seconds apart, up to 3 messages. A step written by AI then writes 2 or 3 short messages (messages it already wrote are cut at their blank lines, so turn it on before enrolling); in a template or a written message, put a blank line between the messages. A later sequence_update must repeat splitMessage, or it is turned off. The daily LinkedIn limit counts the step once. If a later part fails after the first one is out, the step still counts as sent and the missing part is not retried, so the lead never receives a part twice. An Open Profile InMail is always sent as one message.
Context for messages written by AI
A step inai mode writes each lead’s message from the step’s aiPromptInstructions and from the lead’s table row as it is when the message is written: every column under its name, research and AI columns first, qualification criteria as verdicts. A very rich row is cut to fit, raw fields first. A manual lead can also carry context, up to 4,000 characters: what you know about the lead that has no field of its own, such as a recent post or why they fit. It is given to the AI with the lead.
Send messages you wrote
A step can send a message that was written for each lead before enrollment, exactly as written. No variable is filled in and nothing is generated: a message that still holds{{variables}} waits in the review queue instead of being sent.
- Messages written outside Retriever. Give each manual lead its
messages, keyed by step number (the step’s position when its first leads come with messages; later batches and updates keep that number even if steps move):{"1": {"body": "..."}, "3": {"subject": "...", "body": "..."}}. An email step takessubjectandbody. A LinkedIn step takesbodyonly. Send these leads in a request withouttables. The steps you name start to send these texts. To read each message before it is sent, setrequiresReviewon those steps when you create the sequence, before you enroll: the messages wait in the review queue of the Retriever app, where they can be corrected and approved. A latersequence_updatemust repeat each switched step’scontentMode: "column"and column keys (andsplitMessageif set). - Messages written in a table. Set the step’s
contentModetocolumnand give the column key withbodyColumn(andsubjectColumnfor an email). Enroll the leads from that table.
missing_message. Each message is stored when its lead is enrolled, and the stored text is what is sent. To send a corrected version, call sequence_update_messages:
- For leads enrolled from a table, the table is corrected in the Retriever app (by the user, or by the Retriever agent), then call it with the
sequenceId. Every message not sent yet is replaced by the table’s text. - For leads enrolled with their messages, pass
leadswith the lead’semailorlinkedinUrland its newmessages, keyed by the step number used when the leads were enrolled (it does not change when steps are moved). A lead not found among the leads still in the sequence (never enrolled, mistyped, or replied, stopped or finished) is listed innotInSequence; the others are still updated. An invitation note over the LinkedIn limit refuses the request (message_too_long). dryRun: trueonly counts the messages that differ (changed).
kept. A message with no finished text in the table (empty, failed, being written or out of date) keeps its stored text, or waits for review when none was stored, and is counted in missing. An invitation note too long in the table is not taken (tooLong). On a step that requires review, an updated message waits for review again. A stored message that cannot be sent (empty, or too long for an invitation note) waits in the review queue, and the update releases it once the table has its text. Messages for a step that does not exist, or a subject on a LinkedIn step, refuse the whole request. A step that already writes its own messages for leads enrolled earlier cannot take written messages: use a new sequence.
Senders
Shared inbox
MCP annotations
Tools expose MCP hints (readOnlyHint, destructiveHint, idempotentHint) so the host knows when to ask the user first. These tools are marked destructive: retriever_build_list_cancel, retriever_research_cancel, exclusion_add (a value a CRM integration brought in moves to the API for good), exclusion_remove, scheduled_run_update, scheduled_run_set_status, scheduled_run_run_now, scheduled_run_delete, play_update (it can turn autopilot on), play_launch, play_set_status, play_run_now (a run starts and spends credits), play_lead_accept (the lead’s first message is sent), play_lead_reject (the person and their company are excluded), play_delete, play_proposal_decide, play_lead_replace (a run starts and spends credits), play_lead_rewrite_message, play_lead_save_message, play_rewrite_step_instructions, play_move_leads, sequence_update (a step left out of steps is deleted), sequence_set_status, sequence_delete, sequence_enroll_leads (an active sequence starts sending), sequence_stop_lead, sender_delete and inbox_reply. No tool takes a confirm parameter: a host that honours destructiveHint asks the user before these tools run. Some hosts run tools without asking, so the descriptions of the tools that send, delete or stop something also tell the agent to act only on the user’s explicit request.
Tool results are compact JSON text. When the result is a JSON object, it also comes as structuredContent. A failed call that carries an API error code has { "error", "message" } there.
Verify the tool list from a client
After connecting, your MCP client exposestools/list. In the monorepo:
server-contract.test.ts contract test pins expected tool names in the repo—useful to catch doc drift.