Landbase MCP tools

Landbase MCP gives an assistant a complete workflow for B2B prospecting:

Choose the Landbase account.
Search for companies or people, or inspect an existing dataset.
Preview and optionally transform the dataset.
Match, enrich, qualify, or research rows.
Poll the asynchronous run and use its output dataset.
Publish and download the final file when needed.

The server exposes account, search, dataset, workflow, and record-matching tools. It also exposes two guided prompts and the landbase://capabilities resource for clients that support those MCP features.

How to choose a tool

Goal	Start with	Then use
Build a new prospect list	`search`	`get_search_result`, `get_dataset`, `preview_dataset`
Find one company	`match_company`	—
Find one person	`match_person`	—
Match many rows	`match_dataset`	`get_workflow_run`
Add attributes	`enrich_dataset`	`get_workflow_run`
Ask yes/no questions per row	`qualify_dataset`	`get_workflow_run`
Research one question per row	`research_dataset`	`get_workflow_run`
Find contact details	`enrich_contacts`	`get_workflow_run`
Limit or select rows	`transform_dataset`	`get_workflow_run`
Download a dataset	`publish_dataset` if required	`get_download_url`
Upload a small CSV/JSONL file	`upload_dataset`	`get_dataset`, `preview_dataset`
Inspect authoritative fields	`get_dataset_fields`	—
Trace dataset provenance	`get_dataset_lineage`	—

Use the typed workflow tools when one matches the task. Use run_workflow when you need one of the less common workflow types or need to pass workflow-specific parameters not covered by a typed tool.

Account context

`list_accounts`

Returns the signed-in user, the Landbase accounts they belong to, and the current default account when one exists. Call this first when the user might belong to multiple accounts:

{}

Example result:

{
  "user": {"email": "ada@example.com", "name": "Ada Lovelace"},
  "accounts": [
    {"id": "447", "name": "GTM", "role": "Owner", "wallet_status": "active"}
  ],
  "default_account_id": "447"
}

If more than one account is returned, ask the user which account to use. Once selected, pass its string account_id on every account-scoped call, including reads, writes, polling, recovery, confirmation calls, and downloads. The server does not retain the selection between calls. A dataset ID, run ID, or search handle does not replace account context. The request examples below use "account_id": "447"; replace it with the chosen account ID. list_accounts itself has no account_id argument. Response examples may omit account context, but follow-up calls must still include it. Never guess or silently choose an account.

`get_credit_balance`

Returns the current credit balance for the selected account:

{"account_id": "447"}

Keep the selected account_id on subsequent calls even when the result does not repeat it.

Building prospect lists

`search`

Builds a company or people dataset from a natural-language request. Important inputs:

query — what to find, in plain language.
mode — default builds a list; research handles SQL-style questions and aggregations.
session_id — reuse the session ID from an earlier search to refine that search instead of starting an unrelated conversation.
wait_seconds — wait up to 40 seconds for a result before returning a running handle.
account_id — selected Landbase account; keep it on follow-up calls.

Example:

{
  "query": "VPs of Sales at B2B SaaS companies in Texas with 50-200 employees",
  "mode": "default",
  "wait_seconds": 40,
  "account_id": "447"
}

A completed result includes an answer and usually a dataset_id:

{
  "status": "completed",
  "session_id": "4f2d...",
  "dataset_id": "ds-abc123",
  "answer": "Found companies matching the request."
}

Searches can outlive an MCP client’s tool-call timeout. In that case the first response is a running handle:

{
  "status": "running",
  "handle": "srch_<opaque-handle>",
  "session_id": "4f2d..."
}

Do not submit the same query again while it is running. To refine a completed search, call search with its session_id, the selected account_id, and a new query. Research mode can finish its first turn with a SQL proposal and credit quote but no dataset. After user approval, call search with query: "confirm", mode: "research", and the original session_id and account_id. Do not pass confirm: true to search; it has no such argument. See Research search approval.

`get_search_result`

Polls a running search using the opaque handle returned by search. wait_seconds may be 0-40. Call it again while the result has status: "running", passing the same account_id on every poll.

{
  "handle": "srch_<opaque-handle>",
  "wait_seconds": 40,
  "account_id": "447"
}

The handle is safe to pass to a later MCP connection; do not decode or modify it. If the search completes with a workflow ID, poll that workflow separately with get_workflow_run and the same account_id.

Agent-run status and recovery

Search results can include an agent_run_id. Keep it alongside the search handle and session ID. These tools inspect existing runs; they do not start a new search.

`get_agent_run`

Read one status snapshot by exact run ID:

{"run_id": "agent-run-123", "account_id": "447"}

`wait_for_agent_run`

Wait up to 40 seconds for an exact run:

{"run_id": "agent-run-123", "wait_seconds": 40, "account_id": "447"}

An outcome of wait_expired means the local wait ended while the operation may still be running. Call wait_for_agent_run again with the same run ID and account_id. Terminal outcomes are completed, failed, and cancelled. If the result includes a workflow_run_id, inspect that workflow with get_workflow_run and the same account_id.

`list_agent_runs`

Recover the runs associated with the original session when a trigger response was lost:

{
  "session_id": "00000000-0000-4000-8000-000000000001",
  "agent": "fast_dataset_creator",
  "account_id": "447"
}

Use the real session ID from the original operation. The agent can be fast_dataset_creator, advanced_dataset_creator, or tam_map_creator; select the agent that started the run, rather than assuming every session is a default search. Default search uses fast_dataset_creator; research search uses advanced_dataset_creator.

`get_latest_agent_run`

Read the latest run in an agent session. It accepts the same session_id, agent, and account_id arguments as list_agent_runs:

{
  "session_id": "00000000-0000-4000-8000-000000000001",
  "agent": "fast_dataset_creator",
  "account_id": "447"
}

Prefer an exact run ID once you have recovered it so a later run cannot be mistaken for the operation you are waiting on.

Dataset inspection and files

`list_datasets`

Lists datasets newest first. Use limit (1-100) and offset for pagination:

{"limit": 20, "offset": 0, "account_id": "447"}

`get_dataset`

Returns dataset metadata, row count, and column names:

{"dataset_id": "ds-abc123", "account_id": "447"}

Use this before a workflow when you need to know the number of rows or available columns. If the row count is zero, there are no rows to preview or enrich. Set include_runs: true when you also need processing run summaries.

`get_dataset_fields`

Returns the authoritative field names without downloading the dataset. Use this when you only need schema information:

{"dataset_id": "ds-abc123", "account_id": "447"}

`preview_dataset`

Returns up to 100 rows. The optional SQL must be a read-only DuckDB SELECT against a table named input_dataset:

{
  "dataset_id": "ds-abc123",
  "sql": "SELECT company_name, website FROM input_dataset WHERE employee_count > 100",
  "limit": 20,
  "account_id": "447"
}

If sql is omitted, the tool uses SELECT * FROM input_dataset. Long cell values are trimmed for safe tool responses. An empty rows result means the dataset is empty or the query matched nothing.

`upload_dataset`

Uploads bounded CSV or JSONL text supplied by the MCP client. It accepts up to 5 MiB and does not read a client-local filesystem path. For larger files, use the Landbase UI or CLI. After upload, call get_dataset to inspect processing status and fields:

{
  "filename": "prospects.csv",
  "content": "company_name,website\nAcme,https://acme.example\n",
  "account_id": "447"
}

`get_dataset_lineage`

Returns the datasets and processing history that produced a dataset. Use this when explaining where an output came from or before deleting derived data:

{"dataset_id": "ds-abc123", "account_id": "447"}

`delete_dataset`

Permanently deletes a dataset. The first call only returns a confirmation request; repeat with confirm: true after the user explicitly agrees:

{"dataset_id": "ds-abc123", "confirm": true, "account_id": "447"}

`publish_dataset`

Creates one downloadable file from a dataset. Supported formats are csv, jsonl.gz, and parquet:

{
  "dataset_id": "ds-abc123",
  "format": "csv",
  "account_id": "447"
}

The tool starts an asynchronous workflow and returns a workflow_run_id. Poll it with get_workflow_run, keeping the same account_id; after it succeeds, download the output dataset with that account ID. Publishing is also required when a dataset is partitioned and cannot be downloaded directly.

`get_download_url`

Returns a temporary download link. Downloading costs credits, so call it once without confirmation first:

{"dataset_id": "ds-abc123", "account_id": "447"}

The first result has status: "needs_confirmation", row_count, and a next-step instruction. After the user agrees, repeat with confirm: true:

{"dataset_id": "ds-abc123", "confirm": true, "account_id": "447"}

The confirmed result has status: "ready", download_url, and an expiry of about 30 minutes. Give the URL to the user promptly. If the tool says the dataset must be published, call publish_dataset, poll its workflow, and use that workflow’s output_dataset_id.

Matching individual records

`match_company`

Looks up one company using a website, company name, or LinkedIn URL. A website or LinkedIn URL is more precise than a name alone:

{"company_website": "https://example.com", "account_id": "447"}

Optional inputs include company_name, linkedin_url, and hq_country. At least one of company_website, company_name, or linkedin_url is required. For many rows, use match_dataset instead.

`match_person`

Looks up one person using a LinkedIn URL, email, or a full name with company context:

{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "company_name": "Analytical Engines",
  "account_id": "447"
}

A LinkedIn URL or email is the strongest identifier. A full name requires both first_name and last_name plus company_name or company_website. Treat a plausible match as unverified and inspect the returned record before reporting it as confirmed.

Dataset workflows

Workflow calls return a bounded status snapshot. A workflow may still be in progress when the tool returns. Poll with:

{
  "run_id": "workflow-run-123",
  "wait_seconds": 40,
  "account_id": "447"
}

Use output_dataset_id after SUCCEEDED; it is the workflow’s output dataset, not the input dataset. Terminal statuses are SUCCEEDED, FAILED, and CANCELLED. Do not retry a failed workflow without changing the cause. Use cancel_workflow_run only when the user asks to stop work.

`match_dataset`

Matches many company or person rows to Landbase records.

{
  "dataset_id": "ds-abc123",
  "enable_name_to_website": false,
  "account_id": "447"
}

`enrich_dataset`

Adds selected company and/or person attributes. This spends credits:

{
  "dataset_id": "ds-abc123",
  "company_enrich_fields": [
    "employee_count",
    "industry"
  ],
  "person_enrich_fields": [
    "job_title",
    "email"
  ],
  "account_id": "447"
}

Call first without confirm. If the result is needs_confirmation, show the estimate and repeat the same call, including the selected account_id, with confirm: true only after the user agrees.

`qualify_dataset`

Runs one or more AI yes/no qualification questions for each row:

{
  "dataset_id": "ds-abc123",
  "qualification_prompts": [
    "Is this company a B2B SaaS business?"
  ],
  "context_cols": [
    "company_name",
    "website"
  ],
  "entity_type": "company",
  "enable_web_search": false,
  "account_id": "447"
}

This spends credits and requires the same quote-then-confirm flow. entity_type is company or person.

`research_dataset`

Runs one AI research task per row. The typed tool accepts one task at a time:

{
  "dataset_id": "ds-abc123",
  "research_task_name": "pricing",
  "prompt": "Find the public pricing model and summarize it in one sentence.",
  "context_cols": [
    "website"
  ],
  "enable_web_search": true,
  "account_id": "447"
}

This spends credits and requires confirmation. Keep the prompt focused and use only the columns needed for the task.

`enrich_contacts`

Finds contact email addresses and/or phone numbers:

{
  "dataset_id": "ds-abc123",
  "enrich_email_address": true,
  "enrich_phone_number": false,
  "account_id": "447"
}

This spends credits and requires confirmation. Request only the contact fields needed for the user’s goal.

`transform_dataset`

Creates a new dataset from a read-only SQL query. It is useful for limiting rows before a paid workflow:

{
  "dataset_id": "ds-abc123",
  "sql": "SELECT * FROM input_dataset LIMIT 100",
  "account_id": "447"
}

Use the returned workflow’s output_dataset_id for the next step.

`run_workflow`

The generic workflow tool supports onboard, match, enrich_only, qualify, research, dataset_transform, similar_company_expansion, and contact_enrich. Its params object follows the workflow-specific shapes in the tool description. Prefer the typed tools above when available. For example, the generic form of a match call is:

{
  "workflow": "match",
  "dataset_id": "ds-abc123",
  "params": {
    "enable_name_to_website": false
  },
  "account_id": "447"
}

`get_workflow_run`

Polls a workflow_run_id from run_workflow, a typed workflow tool, or a search/publish result. It waits up to 40 seconds and returns progress such as percentage, rows_processed, and current_stage when available.

{"run_id": "workflow-run-123", "wait_seconds": 40, "account_id": "447"}

`cancel_workflow_run`

Cancels a running workflow. Only call it after the user explicitly asks to stop that workflow:

{"run_id": "workflow-run-123", "account_id": "447"}

Cancellation does not roll back rows already written or credits already spent. Inspect the run and its lineage before deciding whether any output is usable.

Guided prompts and capabilities resource

Clients that support MCP prompts can use build_prospect_list or enrich_dataset to start a guided workflow. Prompts are suggestions for the model; they do not execute tools themselves. Clients that support MCP resources can read landbase://capabilities for a short version of the tool catalog, async rules, and confirmation requirements.

Common errors and recovery

Multiple accounts: call list_accounts, ask the user to choose, and pass account_id.
needs_confirmation: show the estimate or row count and ask for explicit agreement; keep the same account_id on the confirmed call and do not set confirm automatically.
Running search/workflow: poll the returned handle or run ID; do not start a duplicate operation.
PUBLISH_REQUIRED: publish the dataset, poll that workflow, and download the output dataset.
Insufficient credits: tell the user and do not retry.
Rate-limited status read: wait for the indicated delay, then retry the same read. If it fails again, report the error.
Timed-out call that starts work: recover the existing operation before retrying. A lost response does not mean no work started. See Continue a search or workflow.

For copy/paste task prompts, see the MCP prompt cookbook. For connection and recovery symptoms, see Troubleshoot MCP.

​Landbase MCP tools

​How to choose a tool

​Account context

​list_accounts

​get_credit_balance

​Building prospect lists

​search

​get_search_result

​Agent-run status and recovery

​get_agent_run

​wait_for_agent_run

​list_agent_runs

​get_latest_agent_run

​Dataset inspection and files

​list_datasets

​get_dataset

​get_dataset_fields

​preview_dataset

​upload_dataset

​get_dataset_lineage

​delete_dataset

​publish_dataset

​get_download_url

​Matching individual records

​match_company

​match_person

​Dataset workflows

​match_dataset

​enrich_dataset

​qualify_dataset

​research_dataset

​enrich_contacts

​transform_dataset

​run_workflow

​get_workflow_run

​cancel_workflow_run

​Guided prompts and capabilities resource

​Common errors and recovery