Skip to main content
This page lists tools registered by the hosted MCP server (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, use retriever_build_list_start.

Workspaces

A workspace holds the tables of a list. Its id 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 of invite, 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 an invite 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 reason missing_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 duplicates now means running_elsewhere, so a lead still running in another sequence is skipped where it used to be enrolled; send duplicates: "allow" to keep the old behaviour. duplicates decides 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 (reason running_in_another_sequence); a lead whose other sequence is finished can be enrolled again. any_sequence skips the leads another sequence has contacted or is contacting (reason in_another_sequence); leads only staged on a draft are not counted, for either rule. allow enrolls them anyway, and alsoRunningElsewhere counts 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_available only 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 LinkedIn message 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 in ai 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 takes subject and body. A LinkedIn step takes body only. Send these leads in a request without tables. The steps you name start to send these texts. To read each message before it is sent, set requiresReview on 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 later sequence_update must repeat each switched step’s contentMode: "column" and column keys (and splitMessage if set).
  • Messages written in a table. Set the step’s contentMode to column and give the column key with bodyColumn (and subjectColumn for an email). Enroll the leads from that table.
Enroll once the message column has finished writing: a lead whose message is empty, failed or still being written is skipped at enrollment with the reason 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 leads with the lead’s email or linkedinUrl and its new messages, 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 in notInSequence; the others are still updated. An invitation note over the LinkedIn limit refuses the request (message_too_long).
  • dryRun: true only counts the messages that differ (changed).
A message edited by hand in the review queue keeps the edit, and a message being sent stays as it is: both are counted in 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 exposes tools/list. In the monorepo:
Configure the API base URL and API key in your shell before live MCP smoke tests outside the monorepo. The server-contract.test.ts contract test pins expected tool names in the repo—useful to catch doc drift.