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 isNo 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
- Call
modem_agent_invokewith the question as the user asked it, for example “Which customers asked for SSO this quarter, and which Linear issues track it?” - Call
modem_agent_get_runwithwait_seconds: 25, and again right away while the status isworking. When the run completes, readresult.text. - When the next question builds on that answer, call
modem_agent_send_messagein the same conversation.
Triage topics
- 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”.
- Call
bulk_update_topicsto archive or re-prioritize them, orupdate_topicfor a single change.
You can also ask the agent run to make the change itself.
Deduplicate companies or people
- Ask an agent run for the duplicates and their IDs, for example “Find companies whose name contains Acme and list their IDs”.
- Pick the record to keep as the target.
- Call
merge_companiesormerge_peoplewith 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 |