MCP Tool Reference

This page is the complete reference for the tools the Modem MCP Server exposes at https://mcp.modem.dev/mcp. For client setup and an overview of when to use each tool, see the Modem MCP Server page. The server exposes up to 14 tools, grouped by what they do:

Group	Tools	Scope required
Search	`search_modem`	`data:read`
Agent runs	`modem_agent_invoke`, `modem_agent_get_run`, `modem_agent_send_message`, `modem_agent_cancel_run`	`agent:invoke`
Write	`update_topic`, `bulk_update_topics`, `merge_topics`, `create_companies`, `update_companies`, `merge_companies`, `add_people_to_company`, `update_people`, `merge_people`	`agent:invoke`

Your client only sees the tools covered by the scopes you approved during authorization. A token with data:read alone sees search_modem and nothing else.

How authorization works

The Modem MCP Server uses standard MCP OAuth. Your client discovers and completes the flow on its own; there is no API key.

Discovery

An unauthenticated request to https://mcp.modem.dev/mcp returns 401 with a WWW-Authenticate challenge pointing at the server’s protected-resource metadata (/.well-known/oauth-protected-resource/mcp, also served at the root well-known location). The metadata names Modem’s authorization server.

Client registration

Clients that support OAuth dynamic client registration register themselves automatically. No manual client ID setup is needed.

Browser consent

The client opens a browser window using the OAuth 2.0 authorization code flow with PKCE. On the Modem consent screen you sign in, pick the Modem organization if your account belongs to more than one, and approve the requested permissions (agent:invoke and/or data:read).

Token issue

The client receives an access token bound to your user, the selected organization, and the approved scopes. Clients that request offline_access also receive a refresh token, so you do not re-authorize every session.

The organization is resolved from the token claims on every call. Tool arguments never carry an organization ID, and a client cannot target a different organization than the one approved at consent.

search_modem

Answer a natural-language question about your Modem data and get matching rows back. Read-only. Does not run the full Modem Agent and does not consume agent credits. Requires the data:read scope.

Parameters

Parameter	Type	Required	Description
`question`	string	Yes, unless `cursor` is set	Natural-language data question, 1 to 2,000 characters.
`limit`	number	No	Page size, 1 to 100. When set, the result is paged server-side and a `cursor` comes back when more rows exist.
`cursor`	string	No	Opaque continuation token from a previous response. Fetches the next page of the same result set without re-running the search. No `question` needed.
`columns`	array	No	Requested row shape, 1 to 24 column specs. The returned rows are validated against it and the verdict is reported under `schema` on the result.

Each entry in columns is an object:

Field	Type	Required	Description
`name`	string	Yes	Column name the returned rows should carry, 1 to 64 characters.
`type`	string	Yes	One of `string`, `number`, `boolean`, `timestamp`, `json`. `number` also accepts numeric strings.
`description`	string	No	What the column should contain, up to 200 characters.
`required`	boolean	No	Whether every row must carry this column. Defaults to `true`.

Example

{
    "question": "Which topics have the most feedback from VIP companies in the last 30 days?",
    "limit": 25,
    "columns": [
        { "name": "topic_id", "type": "string" },
        { "name": "title", "type": "string" },
        { "name": "feedback_count", "type": "number" }
    ]
}

Result

The result carries a short natural-language answer plus the structured fields below:

Field	Type	Description
`rows`	array	Rows from the search’s final query.
`rowCount`	number	Number of rows in `rows`.
`answer`	string	Short natural-language summary of the result.
`complete`	boolean	True when `rows` is the complete result set (no truncation, no further pages).
`cursor`	string	Present when more rows are available. Pass it back as the `cursor` parameter to fetch the next page.
`schema`	object	When `columns` was supplied: `{ valid, errors }` reporting whether the rows satisfied the requested shape.
`truncated`	boolean	True when the rows were cut to stay within the result-size cap.
`partial`	boolean	True when the search could not finish exploring; rows and answer may be intermediate.
`warnings`	array	Machine-readable degradation codes: `step_budget_exhausted`, `rows_truncated`, `page_execution_failed`, `answer_narration_stripped`.
`traceId`	string	Trace ID for this call. Quote it when contacting Modem support.

Topic priority values in returned rows are named levels encoded as integers: very_low (-100), low (-50), default (0), high (50), very_high (100).

Agent run tools

The four modem_agent_* tools run the full Modem Agent asynchronously. Starting a run returns immediately with IDs; the run continues in Modem even if your client disconnects. Agent runs consume credits. All four require the agent:invoke scope.

modem_agent_invoke

Start a new durable agent conversation.

Parameter	Type	Required	Description
`prompt`	string	Yes	Natural-language prompt for the Modem Agent, 1 to 50,000 characters.
`idempotency_key`	string	Yes	Stable retry key. Reuse only for the exact same prompt.

{
    "prompt": "Which customers requested SSO this quarter, and do any related Linear issues already exist?",
    "idempotency_key": "sso-requests-2026-09-02"
}

Returns conversation_id, run_id, and status: "working".

modem_agent_get_run

Get the current status and, once complete, the result of a run.

Parameter	Type	Required	Description
`conversation_id`	string (UUID)	Yes	Conversation ID returned by `modem_agent_invoke`.
`run_id`	string	Yes	Run ID returned by `modem_agent_invoke` or `modem_agent_send_message`.

Returns:

Field	Type	Description
`status`	string	One of `working`, `completed`, `failed`, `cancelled`.
`result`	object	Present when completed: `{ text }` with the agent’s answer.
`error`	object	Present when failed: `{ code, message, retryable }`.
`accepted_at`	string	When the run was accepted.
`updated_at`	string	When the run state last changed.

Poll this tool until the status is terminal. The tool is read-only and safe to call repeatedly.

modem_agent_send_message

Start a follow-up turn in an existing MCP conversation. Wait for the current run to finish first; only one turn can run in a conversation at a time.

Parameter	Type	Required	Description
`conversation_id`	string (UUID)	Yes	Existing MCP conversation ID.
`prompt`	string	Yes	Follow-up prompt, 1 to 50,000 characters.
`idempotency_key`	string	Yes	Stable retry key for this follow-up. Use a new key per turn.

Returns conversation_id, run_id, and status: "working" for the new turn.

modem_agent_cancel_run

Cooperatively cancel one exact run. Actions the agent already completed are not reversed.

Parameter	Type	Required	Description
`conversation_id`	string (UUID)	Yes	Conversation ID.
`run_id`	string	Yes	Run ID to cancel.

Returns status: "cancelled", or status: "already_terminal" if the run had already finished.

Write tools

Write tools apply changes directly, without going through the agent. They run as you: each call is authorized against your own role in the organization you approved during consent, exactly like the Modem dashboard. All write tools require the agent:invoke scope and are annotated as destructive, so most clients ask you to confirm each call. ID formats: topic IDs are UUIDs; company and person IDs are numeric strings. Use search_modem to find IDs before calling a write tool.

update_topic

Update a single topic. At least one optional field must be provided.

Parameter	Type	Required	Description
`topicId`	string	Yes	Topic ID (UUID).
`priority`	string	No	One of `very_low`, `low`, `default`, `high`, `very_high`.
`lifecycleState`	string	No	One of `open`, `in_progress`, `completed`, `dismissed`. The `unknown` state is AI-assessed and cannot be set.
`issueType`	string	No	One of `bug_report`, `feature_request`, `complaint`, `praise`, `discussion`, or `null` to clear.
`keywords`	array	No	Replaces the full keyword list. Up to 20 keywords, each 1 to 50 characters.
`archived`	boolean	No	`true` to archive, `false` to unarchive.
`archivedReason`	string	No	Optional reason, up to 4,000 characters. Only used when `archived` is `true`.

{
    "topicId": "3f9d2a10-8c4e-4b7a-9f21-6e5d0c1b2a34",
    "priority": "high",
    "lifecycleState": "in_progress"
}

bulk_update_topics

Update up to 100 topics at once. At least one optional field must be provided; it applies to every topic in the list.

Parameter	Type	Required	Description
`topicIds`	array	Yes	1 to 100 topic IDs.
`priority`	string	No	Set all topics to this priority.
`archived`	boolean	No	`true` to archive, `false` to unarchive all listed topics.
`archivedReason`	string	No	Optional reason, up to 4,000 characters.

Returns updatedCount and updatedTopicIds.

merge_topics

Merge up to 50 source topics into a target topic. Source topics are archived and marked as merged; their group and event associations move to the target. Rejects if any source topic is already archived.

Parameter	Type	Required	Description
`sourceTopicIds`	array	Yes	1 to 50 topic IDs to merge. Must not include the target.
`targetTopicId`	string	Yes	The topic that is kept and receives the merged content.

Returns mergedCount and targetTopicId.

create_companies

Create up to 50 companies. Batch-first with partial success: each company is created independently and the result reports success or an error per item.

Parameter	Type	Required	Description
`companies`	array	Yes	1 to 50 items, each `{ name, domain }`. Both required, up to 255 characters.

{
    "companies": [
        { "name": "Acme", "domain": "acme.com" },
        { "name": "Globex", "domain": "globex.io" }
    ]
}

Returns a results array with { name, domain, success, data?, error? } per item.

update_companies

Update up to 50 existing companies. Partial success per item.

Parameter	Type	Required	Description
`companies`	array	Yes	1 to 50 update items.

Each item:

Field	Type	Required	Description
`companyId`	string	Yes	Company ID (numeric string).
`name`	string	No	New company name.
`logoUrl`	string	No	Logo URL, or `null` to clear.
`isVip`	boolean	No	Mark or unmark the company as VIP.
`primaryDomain`	string	No	Primary domain, or `null` to clear.
`connections`	object	No	External links: `email`, `phone`, `linkedin`, `github`, `twitter`. Only provided fields change; `null` clears one.

merge_companies

Merge one or more source companies into a target company. All domains, person associations, and Slack workspaces move to the target.

Parameter	Type	Required	Description
`targetCompanyId`	string	Yes	The company that is kept.
`sourceCompanyIds`	array	Yes	One or more company IDs to merge into the target.

Returns mergedCount. Sources are merged one at a time; if a later source fails after earlier ones succeeded, the call still returns success with a mergedCount lower than the number of sourceCompanyIds requested. Check mergedCount against the input length to detect partial completion.

add_people_to_company

Associate one or more people with a company.

Parameter	Type	Required	Description
`companyId`	string	Yes	Company ID.
`personIds`	array	Yes	One or more person IDs to add.

Returns addedCount and skippedCount (people already associated are skipped).

update_people

Update up to 50 existing people. Partial success per item.

Parameter	Type	Required	Description
`people`	array	Yes	1 to 50 update items.

Each item:

Field	Type	Required	Description
`personId`	string	Yes	Person ID (numeric string).
`displayName`	string	No	New display name.
`avatarUrl`	string	No	Avatar URL, or `null` to clear.
`description`	string	No	Free-text description, or `null` to clear.
`isVip`	boolean	No	Mark or unmark the person as VIP.
`primaryEmail`	string	No	Primary email address, or `null` to clear.
`connections`	object	No	External links: `linkedin`, `github`, `twitter`, `website`, `phone`, `title`. Only provided fields change; `null` clears one.

merge_people

Merge one or more source people into a target person. All identities, emails, and company associations move to the target.

Parameter	Type	Required	Description
`targetPersonId`	string	Yes	The person that is kept.
`sourcePersonIds`	array	Yes	One or more person IDs to merge into the target.

Returns mergedCount. Sources are merged one at a time; if a later source fails after earlier ones succeeded, the call still returns success with a mergedCount lower than the number of sourcePersonIds requested. Check mergedCount against the input length to detect partial completion.

Common workflows

Triage topics

Call search_modem to find the topics to act on, for example “topics about the old billing page”.
Take the topic IDs from the returned rows.
Call bulk_update_topics to archive or re-prioritize them, or update_topic for a single change.

Deduplicate companies or people

Call search_modem for the duplicates, for example “companies whose name contains Acme”.
Pick the record to keep as the target.
Call merge_companies or merge_people with the target and the source IDs. Merges are not reversible, so confirm the target first.

Cross-tool work through the agent

The MCP write tools only change Modem records. For work that reaches your connected tools, such as creating a Linear issue from a topic or posting to Slack, use an agent run:

Call search_modem to gather the context, for example the highest-priority bug reports this week.
Call modem_agent_invoke with a prompt that includes that context and the action, for example “Create a Linear issue summarizing this feedback”.
Poll modem_agent_get_run until the run completes.

Errors

Tool calls fail with standard MCP tool errors carrying one of these codes:

Code	Meaning
`UNAUTHORIZED`	The token is invalid, or the token’s user no longer has access.
`FORBIDDEN`	The token is missing the required scope, or your role in the organization does not permit the change.
`NOT_FOUND`	The target record, conversation, or run does not exist in the authorized organization.
`BAD_REQUEST`	The arguments failed validation.
`CONFLICT`	An `idempotency_key` was reused with a different prompt, or the conversation is busy.
`TOO_MANY_REQUESTS`	Rate limited. The error carries a `retryAfter` hint in seconds; back off before retrying.
`INTERNAL_SERVER_ERROR`	Something went wrong on Modem’s side. Retry, and quote the `traceId` if you contact support.

Limits

Limit	Value
Tool calls	20 per minute, per organization, per tool
Agent runs	Additionally subject to your organization’s agent credits
`prompt` length	50,000 characters
`question` length	2,000 characters
`search_modem` page size	100 rows
`search_modem` columns	24 requested columns
Topics per bulk update	100
Source topics per merge	50
Companies per create or update	50
People per update	50

Modem MCP Server

Client setup, authorization, and troubleshooting.

The Modem Agent

What the Modem Agent can query and do.

Getting Started

Using Modem

Ingest API

Modem MCP Server

Account

MCP Tool Reference

How authorization works

search_modem

Parameters

Example

Result

Agent run tools

modem_agent_invoke

modem_agent_get_run

modem_agent_send_message

modem_agent_cancel_run

Write tools

update_topic

bulk_update_topics

merge_topics

create_companies

update_companies

merge_companies

add_people_to_company

update_people

merge_people

Common workflows

Triage topics

Deduplicate companies or people

Cross-tool work through the agent

Errors

Limits

Modem MCP Server

The Modem Agent

​How authorization works

​search_modem

​Parameters

​Example

​Result

​Agent run tools

​modem_agent_invoke

​modem_agent_get_run

​modem_agent_send_message

​modem_agent_cancel_run

​Write tools

​update_topic

​bulk_update_topics

​merge_topics

​create_companies

​update_companies

​merge_companies

​add_people_to_company

​update_people

​merge_people

​Common workflows

​Triage topics

​Deduplicate companies or people

​Cross-tool work through the agent

​Errors

​Limits

​Related

Modem MCP Server

The Modem Agent

How authorization works

search_modem

Parameters

Example

Result

Agent run tools

modem_agent_invoke

modem_agent_get_run

modem_agent_send_message

modem_agent_cancel_run

Write tools

update_topic

bulk_update_topics

merge_topics

create_companies

update_companies

merge_companies

add_people_to_company

update_people

merge_people

Common workflows

Triage topics

Deduplicate companies or people

Cross-tool work through the agent

Errors

Limits

Related