> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retriever.run/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Reference for tools exposed by the Retriever MCP server at /mcp.

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)](/mcp).

## Account

| Tool      | Purpose                                                   |
| --------- | --------------------------------------------------------- |
| `credits` | Remaining credit balance (`remainingCredits`). Read-only. |

## Public services (level 1)

| Tool               | Purpose                                                           |
| ------------------ | ----------------------------------------------------------------- |
| `service_discover` | List or search services (`query`, `category`, pagination).        |
| `service_inspect`  | Input/output schemas and pricing metadata for a `service`.        |
| `service_execute`  | Run a service with `{ service, input }`. Does not create a table. |

**Resource**: `retriever://skills/retriever-services` — instructions for the discover → inspect → execute loop.

`service_discover` filter categories: `contacts`, `companies`, `jobs`, `web`, `social`, `ads`, `generate`.

## List-building (agent runs)

| Tool                          | Purpose                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| `retriever_build_list_start`  | Start an async run from a brief (`prompt`, optional `workspace_id`, `output_tables`). |
| `retriever_build_list_get`    | Status, progress, output tables; first page of rows when `completed`.                 |
| `retriever_build_list_cancel` | Cancel a running run.                                                                 |

REST equivalent: `POST /v1/runs`, `GET /v1/runs/{id}`, cancel via the runs API.

## Autonomous research (Go)

| Tool                        | Purpose                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `retriever_research_start`  | Start a multi-step investigation (`query`, optional `output_schema`, `model`, `max_steps`). |
| `retriever_research_get`    | Read status and structured result or synthesis.                                             |
| `retriever_research_cancel` | Cancel in-flight research.                                                                  |

## Tables

| Tool             | Purpose                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `table_list`     | Tables in a workspace (optional `workspace_id` defaults to the first accessible workspace). |
| `table_get`      | Schema, columns, and row count.                                                             |
| `table_get_rows` | Paginated rows (`table_id`, optional `run_id` for run output, `cursor`).                    |
| `table_export`   | Export a table (format and options per tool schema).                                        |

## Sequences (outreach)

| Tool                    | Purpose                                                                  |
| ----------------------- | ------------------------------------------------------------------------ |
| `sequence_list`         | List sequences (`status`, `query`).                                      |
| `sequence_get`          | Sequence detail.                                                         |
| `sequence_create`       | Create a draft (does not activate the sequence).                         |
| `sequence_update`       | Update name, steps, settings.                                            |
| `sequence_set_status`   | `active`, `paused`, `archived` — activate only on explicit user request. |
| `sequence_delete`       | Permanent deletion.                                                      |
| `sequence_enroll_leads` | Enroll leads (from a table or manual input).                             |
| `sequence_list_leads`   | Paginated enrollments.                                                   |
| `sequence_stop_lead`    | Remove one enrollment.                                                   |
| `sequence_trigger_tick` | **Admin only** — global worker tick (admin token required).              |

## Senders

| Tool            | Purpose                              |
| --------------- | ------------------------------------ |
| `sender_list`   | Sender accounts visible to the user. |
| `sender_delete` | Disconnect a sender.                 |

## Shared inbox

| Tool          | Purpose                                                       |
| ------------- | ------------------------------------------------------------- |
| `inbox_list`  | Conversations (`view`, sequence / interest / search filters). |
| `inbox_get`   | Conversation detail.                                          |
| `inbox_reply` | Reply (email or LinkedIn).                                    |
| `inbox_sync`  | Request inbox sync (may be refused when worker-only).         |

## MCP annotations

Many tools expose MCP hints (`readOnlyHint`, `destructiveHint`) so host agents know when to ask for confirmation. Destructive or sensitive operations often accept `confirm: true` by default.

## Verify the tool list from a client

After connecting, your MCP client exposes `tools/list`. In the monorepo:

```bash theme={null}
cd apps/mcp-server && npm test -- test/server-contract.test.ts
```

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.