Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

MCP Tool Reference

Parameters, results, and examples for every tool on the Modem MCP Server

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 20 tools, grouped by what they do:

Group Tools Scope required
Skills modem_skills data:read or agent:invoke
Docs modem_docs data:read or agent:invoke
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
Automations list_automations data:read
Automations create_automation, update_automation agent:invoke
Feedback create_feedback_channel agent:invoke
Feedback send_feedback data:read or agent:invoke

Your client only sees the tools covered by the scopes you approved during authorization. A token with data:read alone sees modem_skills, modem_docs, list_automations, and send_feedback; a token with agent:invoke alone sees modem_skills, modem_docs, send_feedback, the agent-run tools, the write tools, create_automation, update_automation, and create_feedback_channel.

For questions about your organization’s data, and for most other work, the server directs clients to the agent run tools. The agent has more tools, context, and steps than the direct tools, so a token without agent:invoke cannot answer data questions.

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.

modem_skills

Skills that teach an MCP client how to use this server’s tools. Call it when you are unsure which tool to use. Read-only.

Requires either the data:read or the agent:invoke scope, so every token can read the skills for the tools it holds.

This is not the Skills page in Modem (Settings → Skills), and it is not a general skill reader. It cannot load SKILL.md files, harness skills, or organization-authored skills.

Parameters

Parameter Type Required Description
name string No A skill from this server’s catalog, for example agent-runs. Omit (or pass an empty string) to list the catalog.

Result

The result is markdown text.

  • With no name, the result is the catalog, a list of skill names and descriptions.
  • With a known name, the result is that skill’s body.
  • With an unknown name, the result is No skill named … followed by the catalog. The call still succeeds.

The catalog has four skills:

Name Covers
agent-runs When to ask the Modem Agent, passing your question through as written, waiting for the result with modem_agent_get_run, continuing a conversation, and cancelling.
write-tools Getting IDs from an agent run or from you, confirming merges, and reading partial results from the write tools.
install-feedback Adding Modem feedback to an app: create_feedback_channel, wiring in its token, and a test item.
automations Listing, creating, and changing automations: schedules, prompts, output channels, and model levels.

Example

List the catalog:

{}

Load the agent-runs skill:

{ "name": "agent-runs" }

modem_docs

Search or read the Modem docs to answer how Modem works: setup, integrations, this MCP server and its scopes, and the API. Read-only. Does not consume agent credits. For questions about your organization’s data, start an agent run.

Requires either the data:read or the agent:invoke scope.

Parameters

Send exactly one of the two.

Parameter Type Required Description
query string Yes, unless page is set What to look up, 1 to 500 characters. Returns the matching doc sections.
page string Yes, unless query is set A page path as a search result prints it, for example api/modem-mcp-server. Returns the whole page.

Result

The result is markdown text, plus these structured fields:

Field Type Description
mode string search or page.
results array For a search: the matching sections, each with title, page, url, and content (markdown).
markdown string For a page: the page’s full markdown.
truncated boolean True when the result was cut to fit the size cap.

Example

{ "query": "Which scope does modem_agent_invoke need?" }

Agent run tools

The four modem_agent_* tools run the full Modem Agent asynchronously, the same agent as in the Modem dashboard. Use them for questions about your organization’s data and for most other work: the agent queries topics, companies, people, and conversations, and takes action in your connected tools. 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.

Send the user’s question as written. The agent runs as that user and already has the organization’s data, so scope, filters, or an output format the user did not ask for make a run slower without improving the answer. The agent sees its own conversation, not the client’s session: add only context it cannot see, such as the name of a file or pull request the question refers to.

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.
wait_seconds integer No Seconds to wait for the run to finish, from 0 to 25. The call returns as soon as the run finishes. Omit or pass 0 to return at once.

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.

Call this tool with wait_seconds: 25 until the status is terminal. Each call returns when the run finishes, or after 25 seconds with status: "working"; call again right away, without sleeping in between. A waiting call counts once against the rate limit. The tool is read-only and safe to call repeatedly.

modem_agent_send_message

Continue an existing MCP conversation when a question builds on an earlier answer, such as drilling in, narrowing, or acting on the results. The agent keeps the conversation’s context. For an unrelated question, start a new run with modem_agent_invoke. 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. The update and merge tools are annotated as destructive, so most clients ask you to confirm each call. create_companies and add_people_to_company only add data and are not.

ID formats: topic IDs are UUIDs; company and person IDs are numeric strings. Ask an agent run for the IDs before calling a write tool.

update_topic

Update a single topic. At least one of priority, lifecycleState or archived 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 Not supported. Modem derives a topic’s issue type, so sending this field returns an error.
keywords array No Not supported. Modem derives a topic’s keywords, so sending this field returns an error.
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. IDs that match no topic are skipped, and updatedTopicIds lists only the topics that changed.

merge_topics

Not supported yet. Every call returns an error and changes nothing. To retire a duplicate topic, archive it with update_topic and archived: true.

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.

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.

Automation tools

Create, change, and list automations. Like the write tools, they run as you: an automation you create is yours, and you can change only the automations the dashboard lets you edit. list_automations requires data:read; create_automation and update_automation require agent:invoke.

list_automations

List every automation in the organization. Read-only. Call it before creating an automation, to avoid a duplicate and to find the id that update_automation needs.

Parameter Type Required Description
userId string No Only list the automations this user created.

Returns an array of automations. Each has id, name, timezone, schedule, prompt, modelLevel, outputChannels, outcome, enabled, status, nextRunAt, permissions (what you can do with it), creator, and recentRunsSummary (the status and times of its latest runs).

create_automation

Create an automation. It is enabled unless you send enabled: false.

Parameter Type Required Description
name string Yes Name shown in the dashboard.
timezone string Yes IANA time zone, for example America/New_York. Calendar schedules run in it.
schedule object Yes When it runs. See the shapes below.
prompt string Yes* What the agent does on each run. The run has no other context, so include IDs, conditions, and what to do when nothing matches.
modelLevel string No low (Fast), med (Balanced, the default), or high (Smart).
outputChannels array No Where a run may send output. See below.
capabilityMode string No all to allow every connected tool, including ones added later, or custom to allow only allowedCapabilities.
allowedCapabilities array No The tools to allow in custom mode. Defaults to every tool connected now.
enabled boolean No false to create it paused.
sourceDefaultTaskSlug string No The template this automation is created from, if any.
outcome object No What a run does. Omit to run the agent with the prompt. {type: "webhook", url} POSTs each trigger event to that HTTPS URL instead.

* Not needed when outcome is a webhook. A webhook run ignores prompt, modelLevel, outputChannels, and the capabilities. Deliveries are signed with Standard Webhooks; the signing secret is shown only on the automation’s page in the dashboard.

schedule takes one of these shapes. Recurring schedules run at most every 30 minutes.

Shape Runs
{ "type": "at", "at": "<ISO 8601>" } Once, at a future time.
{ "type": "every", "unit": "minutes" | "hours", "n": <number> } At a fixed interval.
{ "type": "cron", "expr": "<cron expression>" } On a cron schedule.
{ "type": "rrule", "rrule": "<RFC 5545 rule>" } On an iCalendar recurrence rule.
{ "type": "event", "events": ["<event name>", ...] } Once per occurrence of any listed event, up to 20 events. The tool description lists them.

An event schedule can also take channelIds or productIds to fire only for those channels or products, delaySeconds (up to 604,800, 7 days) to wait after the event, and, for GitHub pull request events, targetBranches such as ["main", "release/*"]. An activity event shares its schedule only with other conversation activity events (chat.activity, call.activity, support_ticket.activity, feedback.activity, social_post.activity); pull_request.activity, issue.activity, and topic.activity run alone. An activity schedule can take filter, an exact-match expression such as source.name in ['zendesk', 'intercom'] && author.role == 'customer'; see Filters for each event’s fields. It can also take condition, a plain-language “only run when” rule of up to 2000 characters that Modem checks against each event before the run starts; see Trigger conditions. Modem sets conditionMode on the saved schedule; leave it out.

Each outputChannels item is { channel, mode, destinations }:

Field Description
channel slack, email, discord, or msteams.
mode specific sends only to destinations. any lets the run choose. any-internal (Slack only) lets it choose, but never guests, external users, or Slack Connect channels.
destinations For specific, at least one Slack channel ID, email address, or other destination. null for any and any-internal.
{
    "name": "Route new feedback",
    "timezone": "America/New_York",
    "schedule": { "type": "event", "events": ["feedback.created"] },
    "prompt": "Post each new feedback item to Slack channel C0123456789 with a one-line summary. If the item is empty, do nothing.",
    "modelLevel": "low",
    "outputChannels": [{ "channel": "slack", "mode": "specific", "destinations": ["C0123456789"] }]
}

Returns the new automation, with the same fields as a list_automations item apart from creator and recentRunsSummary. A repeated call creates a second automation. Its dashboard page is https://app.modem.dev/<org-slug>/automations/<id>.

update_automation

Change an automation. Send automationId and only the fields that change; every other field keeps its value. It takes the same optional fields as create_automation except sourceDefaultTaskSlug. prompt, schedule, and outputChannels are replaced whole.

Parameter Type Required Description
automationId string (UUID) Yes The id from list_automations.
{
    "automationId": "0193f6b2-6c1e-7a40-9d1c-2f6a8b4e9c11",
    "name": "Route all new feedback",
    "enabled": false
}

Returns the updated automation.

Feedback tools

create_feedback_channel

Create an in-app feedback channel and return its token. Requires the agent:invoke scope and an organization admin; a member gets a FORBIDDEN error. Read the install-feedback skill before calling it: it covers where to store the token and how to confirm a test item arrived.

Parameter Type Required Description
name string Yes The channel’s name, 1 to 100 characters. Use the app’s name.
allowedOrigins array No Browser origins allowed to submit, up to 20, such as ["https://app.example.com", "http://localhost:3000"]. Omit for a non-browser app.

The channel is created in the organization’s default project. The result is { channel, token }. The token is shown only in this response, so store it before doing anything else. Creating a channel is not idempotent: if the call times out, do not call it again; check Settings → Integrations → In-app feedback instead.

send_feedback

Send feedback about Modem to the Modem team. The tool is available on either scope and asks for your approval before it sends. Use it when a Modem tool fails or returns something you cannot act on, or when you want to tell us what you need.

Parameter Type Required Description
message string Yes What you tried, what happened, and what you expected. 1 to 4,096 characters.
name string Yes Your name, up to 256 characters.
email string Yes Your email, so we can follow up.
category string No agent_friction for a failing tool, or user_feedback (the default) for your own words.
url string No The page the report is about.
trace_id string No The traceId from a failed tool call’s error, so we can find it.
release string No Your client’s version.
tags object No Up to 20 labels, such as tool_name and error.
context object No What you were attempting, at most 8,192 characters when serialized.

Returns Feedback sent (id …). When a tool on this server fails with a 5xx, its error carries a traceId and names send_feedback as the way to report it.

Common workflows

Answer a question about your data

  1. Call modem_agent_invoke with the question as the user asked it, for example “Which customers asked for SSO this quarter, and which Linear issues track it?”
  2. Call modem_agent_get_run with wait_seconds: 25, and again right away while the status is working. When the run completes, read result.text.
  3. When the next question builds on that answer, call modem_agent_send_message in the same conversation.

Triage topics

  1. Ask an agent run for the topics to act on and their IDs, for example “List the IDs of topics about the old billing page”.
  2. Call bulk_update_topics to archive or re-prioritize them, or update_topic for a single change.

You can also ask the agent run to make the change itself.

Deduplicate companies or people

  1. Ask an agent run for the duplicates and their IDs, for example “Find companies whose name contains Acme and list their IDs”.
  2. Pick the record to keep as the target.
  3. 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, put the question and the action in one agent run, for example “Find the highest-priority bug reports this week and create a Linear issue summarizing them”. Wait for the result with modem_agent_get_run and wait_seconds: 25.

Errors

An invalid or expired token is rejected with HTTP 401 before any tool runs; re-authorize your client. Otherwise, a failed tool call returns a standard MCP tool error (isError: true) with a human-readable message and no machine-readable code.

Situation Meaning
Unauthorized The token’s user no longer has access.
Forbidden The token lacks the required scope, your role doesn’t permit the change, or the organization has reached its monthly agent usage limit.
Not found The target record, conversation, or run does not exist in the authorized organization, or no docs page has that path.
Invalid arguments The arguments failed validation.
Conflict An idempotency_key was reused with a different prompt, or the conversation is busy.
Rate limited Too many calls to one tool, or, for the agent tools, the organization’s daily agent cost limit. Wait and retry with backoff.
Internal error Something went wrong on Modem’s side. Retry, and contact support if it persists.

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
Topics per bulk update 100
Source topics per merge 50
Companies per create or update 50
People per update 50
Automation schedule interval At least 30 minutes
Events per automation 20

Was this page helpful?