Modem MCP Server
Ask the Modem Agent, update your workspace, and manage automations from Claude, ChatGPT, Cursor, and more
The Modem MCP Server lets MCP-compatible clients work with Modem from outside the Modem dashboard. Use it when you want an external assistant to ask the Modem Agent about your customer feedback, topics, people, and companies, have the agent act in your connected tools, or update your Modem workspace directly.
The quickest way to connect is an official Modem plugin for Claude, ChatGPT, Codex, or Cursor. For any other client, add the server URL yourself.
Install a Plugin
Modem publishes an official plugin in each of these directories. A plugin connects to this same server and signs in with OAuth, so you get the same tools without editing a configuration file.
| Client | Directory | Install |
|---|---|---|
| Claude | Claude Connectors Directory | Install in Claude |
| ChatGPT and Codex | ChatGPT plugin directory | Install in ChatGPT |
| Cursor | Cursor Marketplace | Install in Cursor |
Open the listing
Install the plugin
/add-plugin modem.Authorize Modem
The ChatGPT plugin directory listing covers both ChatGPT and Codex. For a client that is not listed, or to configure the server yourself, use the server URL and the client setup steps below.
Server URL
Use this URL in your MCP client:
https://mcp.modem.dev/mcp
The server uses Streamable HTTP and OAuth. You do not need to create or paste an API key.
Tools
The server exposes six kinds of tools: one that runs the full Modem Agent, one that serves skills for using this server, one that reads the Modem docs, a set that writes to your Modem workspace, a set that manages automations, and two for feedback: creating a feedback channel for your app and sending feedback about Modem.
Which tools your client sees depends on the scopes you approve during authorization. See Security and Access.
For every tool’s full parameter list, result shape, and example invocations, see the MCP Tool Reference.
Run the agent
Agent runs are asynchronous. Starting a run returns its IDs right away. The run keeps going in Modem, even if your MCP client disconnects.
| Tool | What it does | Inputs |
|---|---|---|
modem_agent_invoke |
Starts a new agent conversation and returns its conversation_id and run_id. |
prompt, idempotency_key |
modem_agent_get_run |
Returns the status and, once complete, the agent’s answer. Can wait up to 25 seconds. | conversation_id, run_id, wait_seconds |
modem_agent_send_message |
Continues an existing MCP conversation with a follow-up that builds on its answers. | conversation_id, prompt, idempotency_key |
modem_agent_cancel_run |
Requests cancellation of one run. Actions the agent already completed are not reversed. | conversation_id, run_id |
Use these tools for questions about your Modem data and for most other work. The agent is the same one as in the Modem dashboard: it queries topics, companies, people, and conversations, follows a topic to the pull request or issue that resolved it, and takes action in your connected tools, such as Linear, Slack, or GitHub. Agent runs consume credits. Runs use your organization’s agent model.
How an agent run works
Start the run
Call modem_agent_invoke with a prompt and an idempotency_key. Modem returns conversation_id, run_id, and a working status.
Check the result
Call modem_agent_get_run with both IDs and wait_seconds: 25. The call returns as soon as the run is completed, failed, or
cancelled, or after 25 seconds with status: "working". Call again right away while it is working, without sleeping between
calls. A completed run includes the answer in result.text.
Continue the conversation
Call modem_agent_send_message with the same conversation_id, a new prompt, and a new idempotency_key. Wait for the current run
to finish before starting the follow-up.
Cancel if needed
Call modem_agent_cancel_run with the conversation and run IDs. Cancellation stops remaining work but does not undo actions the
agent already completed.
Save the conversation and run IDs after each start call. You can use them to check the run from a new connection if the original client exits.
Idempotency keys
Give each logical turn a stable, unique idempotency_key.
- Retry the same turn with the same key and the exact same prompt. Modem returns the existing run instead of starting another one.
- Do not reuse a key with a changed prompt. Modem rejects it as a conflict.
- Start each follow-up with a new key. Only one turn can run in a conversation at a time.
Prompts can contain up to 50,000 characters. All four agent-run tools require the agent:invoke scope.
Skills
| Tool | What it does | Scope |
|---|---|---|
modem_skills |
Skills for using this server. Omit name for the catalog; pass name (for example agent-runs) for that skill. |
data:read or agent:invoke |
Your MCP client reads these on its own, so there is nothing to install. See Skills for MCP Clients for how that works. modem_skills is not the Skills page in the Modem dashboard.
Read the docs
| Tool | What it does | Scope |
|---|---|---|
modem_docs |
Searches or reads the Modem docs to answer how Modem works: setup, integrations, scopes, and the API. | data:read or agent:invoke |
modem_docs is read-only and does not consume agent credits.
Write to your workspace
These tools apply changes directly, without going through the agent.
| Tool | What it does |
|---|---|
update_topic |
Update a single topic: priority, lifecycle state, or archived status. |
bulk_update_topics |
Update up to 100 topics at once, such as archiving or re-prioritizing a set. |
merge_topics |
Not supported yet: returns an error and changes nothing. |
create_companies |
Create up to 50 companies. Each needs a name and a domain. |
update_companies |
Update up to 50 existing companies: name, primary domain, logo, VIP status, or connections. |
merge_companies |
Merge source companies into a target company, which is the one kept. |
add_people_to_company |
Associate one or more people with a company. |
update_people |
Update up to 50 existing people: display name, email, description, VIP status, or connections. |
merge_people |
Merge source people into a target person, which is the one kept. |
All write tools require the agent:invoke scope. The update and merge tools are marked as destructive, so most MCP clients ask you to confirm each call before it runs. create_companies and add_people_to_company only add data and are not.
Permissions
Write tools act as you, not as a service account. Each one runs against your existing role in the organization you selected during authorization, enforced the same way as the Modem dashboard. If your account cannot make a change in the dashboard, the tool cannot make it either. If your account is not a member of the selected organization, the call is rejected.
Field values
Some fields only accept a fixed set of values:
| Field | Accepted values |
|---|---|
priority |
very_low, low, default, high, very_high |
lifecycleState |
open, in_progress, completed, dismissed |
issueType |
bug_report, feature_request, complaint, praise, discussion |
Topic IDs are UUIDs. Company and person IDs are numeric strings. Ask an agent run for the IDs you need before calling a write tool.
Manage automations
These tools list, create, and change automations, the prompts Modem runs on a schedule or when an event happens.
| Tool | What it does | Scope |
|---|---|---|
list_automations |
Lists every automation in the organization, with its schedule, outputs, and recent runs. | data:read |
create_automation |
Creates an automation from a name, time zone, schedule, and prompt. | agent:invoke |
update_automation |
Changes the fields you send on one automation, such as its prompt, schedule, or enabled flag. | agent:invoke |
Like the write tools, they act as you: you own the automations you create, and you can change only the ones the dashboard lets you edit.
Feedback
| Tool | What it does | Scope |
|---|---|---|
create_feedback_channel |
Creates an in-app feedback channel and returns its token. Organization admins only. | agent:invoke |
send_feedback |
Sends feedback about Modem to the Modem team, with your approval. | data:read or agent:invoke |
The install-feedback skill walks a coding agent through creating a channel and adding feedback to an app. See In-app Feedback.
Prerequisites
- A Modem account with access to the organization you want to use
- Claude, ChatGPT, Codex, or Cursor to install a plugin
- Any other client must support remote Streamable HTTP MCP servers with OAuth
Client support changes quickly. The examples below cover common MCP clients with remote HTTP support. Your client may use slightly different labels for the same fields, and it must support OAuth for Modem’s server.
Set Up Your Client
These steps add the server to your client by hand. For Claude, ChatGPT, Codex, and Cursor, installing a plugin is quicker. In every case, the server URL is:
https://mcp.modem.dev/mcp
Claude Code
Claude Code can add remote HTTP MCP servers from the CLI.
claude mcp add --transport http modem https://mcp.modem.dev/mcp
Then run /mcp inside Claude Code and complete the browser authorization flow.
Cursor
To install the plugin instead, open the Modem listing in the Cursor Marketplace or run /add-plugin modem in Cursor.
The button adds the server in one click (Cursor 3.15.12 or newer). To add it by hand, open Settings → Cursor Settings → Tools & MCP, then add a new MCP server. Cursor stores MCP configuration in an mcp.json file.
{
"mcpServers": {
"modem": {
"url": "https://mcp.modem.dev/mcp"
}
}
}
If Cursor asks for a transport type, choose Streamable HTTP.
VS Code and GitHub Copilot
VS Code stores MCP configuration in an mcp.json file, either in your user profile or in .vscode/mcp.json for a workspace.
{
"servers": {
"modem": {
"type": "http",
"url": "https://mcp.modem.dev/mcp"
}
}
}
Use MCP: Add Server or MCP: Open User Configuration from the command palette if you prefer to edit through VS Code.
Codex
The Modem plugin in the ChatGPT plugin directory also works in Codex. To add the server from the CLI instead, run:
codex mcp add modem --url https://mcp.modem.dev/mcp
Then authorize the server, which opens the browser flow:
codex mcp login modem
Codex stores MCP configuration in ~/.codex/config.toml if you prefer to edit it directly. auth defaults to oauth, so it can be omitted.
[mcp_servers.modem]
url = "https://mcp.modem.dev/mcp"
auth = "oauth"
Gemini CLI
Gemini CLI installs Modem as an extension from the public modem-dev/mcp repository:
gemini extensions install https://github.com/modem-dev/mcp
Authorize when prompted on first use, or run /mcp auth modem inside Gemini CLI.
opencode
opencode stores MCP configuration in opencode.json. Use "type": "remote" for the Modem server.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"modem": {
"type": "remote",
"url": "https://mcp.modem.dev/mcp"
}
}
}
Leave the headers field out. Modem uses OAuth, so there is no API key to pass. opencode prompts you to authorize the first time you use the server, or you can trigger the flow yourself:
opencode mcp auth modem
ChatGPT
The quickest path is the Modem plugin in the ChatGPT plugin directory.
To connect the server yourself, use Developer mode, which is available on paid plans. Availability can depend on your account and workspace policy, and OpenAI has moved the setting between menus, so check both locations below.
- Open ChatGPT Settings and enable Developer mode. Depending on your ChatGPT version it lives under Security and login, or under Apps (previously Connectors) → Advanced settings.
- In the apps/connectors list, click the add (+) button to create a new connection.
- Give it a name such as
Modemand enter the server URLhttps://mcp.modem.dev/mcp. - If asked for an authentication type, choose OAuth. Create the connection.
- Complete the Modem authorization flow in the browser window that opens, then review the discovered tools.
In a conversation, enable the Modem connection from the composer’s tools menu, then ask questions that use it. ChatGPT asks for confirmation before running write tools.
Other MCP Clients
Use the client’s remote HTTP or Streamable HTTP setup flow. If it asks for fields, use:
| Field | Value |
|---|---|
| Name | modem |
| URL | https://mcp.modem.dev/mcp |
| Transport | Streamable HTTP or HTTP |
| Authentication | OAuth |
Client-specific MCP docs:
| Client | Docs |
|---|---|
| Claude Code | Connect Claude Code to tools via MCP |
| ChatGPT | Connect a remote MCP server to ChatGPT |
| Cursor | Cursor MCP documentation |
| VS Code | MCP configuration reference |
| Codex | Codex MCP documentation |
| Gemini CLI | Gemini CLI extensions |
| opencode | opencode MCP servers |
Authorize Modem
Your MCP client should open a browser window for OAuth authorization the first time it connects.
On the Modem consent screen:
- Confirm the requesting client name.
- Review the redirect destination.
- Choose the Modem organization if your account belongs to more than one.
- Approve the requested permissions.
After authorization completes, your MCP client can call the Modem MCP tools.
Your client sees only the tools covered by the scopes you approved. A token with data:read but not agent:invoke sees modem_skills, modem_docs, list_automations, and send_feedback, and cannot answer questions about your data. modem_skills, modem_docs, and send_feedback are exposed on either scope.
Example Prompts
Your MCP client picks the tool, so phrase the request for the outcome you want. The examples below tend to select the tool noted alongside them.
Questions, multi-step work, and anything involving connected tools, which normally route to modem_agent_invoke:
Changes to your workspace, which normally route to the write tools:
Automations, which normally route to the automation tools:
Your client passes your question to the agent as written. The agent already knows your organization and you, so your client adds only context from its own session that Modem cannot see. To build on an answer, ask your client to continue the existing Modem conversation.
Security and Access
Modem authorizes the MCP client with OAuth. The access token is scoped to the Modem account and organization selected during consent.
The MCP permissions are:
| Scope | Meaning | Tools it exposes |
|---|---|---|
agent:invoke |
Run the Modem Agent on your behalf, and apply changes to your workspace as you. | modem_skills, modem_docs, send_feedback, four agent-run tools, the workspace write tools, create_automation, update_automation, and create_feedback_channel |
data:read |
List automations, and load skills for this server. Does not run the paid agent. | modem_skills, modem_docs, send_feedback, list_automations |
The MCP server resolves the organization from the OAuth token claims, not from the URL. Keep the server URL as https://mcp.modem.dev/mcp.
The write tools additionally enforce your own role in that organization on every call, so an approved token never grants more access than your Modem account already has.
Rate limits
MCP tool calls are rate limited per organization, per tool, at 20 calls per minute. Exceeding it returns a rate-limit error; wait about a minute and retry with backoff. A modem_agent_get_run call that waits counts once, however long it waits. modem_agent_invoke and modem_agent_send_message are additionally subject to your organization’s agent credit limits.
Troubleshooting
My MCP client does not show the Modem tools
- Confirm the server URL is exactly
https://mcp.modem.dev/mcp. - Restart the client or reload its MCP server list.
- Make sure your client supports remote Streamable HTTP MCP servers with OAuth.
Some tools are missing but others work
Tools are exposed by scope. If you see modem_skills, modem_docs, list_automations, and send_feedback but no agent or write
tools, your token carries data:read but not agent:invoke. Re-run the OAuth flow and approve both permissions.
Authorization fails or returns unauthorized
- Sign in with the Modem account that belongs to the organization you selected.
- Re-run the OAuth flow and approve the requested permissions.
- If authorization still fails, contact Modem support.
A write tool returns forbidden
Write tools run as you, under your role in the selected organization. Confirm your account can make the same change in the Modem dashboard, and that it is a member of the organization you authorized.
A tool call is rate limited
MCP tool calls are limited to 20 per minute per organization, per tool. Wait about a minute and retry with backoff. If an agent tool is rejected for cost rather than rate, retries keep failing until usage over the last 24 hours drops below the daily limit, or, for the monthly usage limit, until your allowance resets.
The agent call returned before the answer was ready
modem_agent_invoke and modem_agent_send_message return as soon as Modem accepts the run. Use the returned conversation_id and
run_id with modem_agent_get_run until the run reaches a final status.
A follow-up returns a conflict
Wait for the current run to finish before sending another message in the same conversation. If you are retrying a request, reuse its
idempotency_key only when the prompt is unchanged.
My client disconnected during an agent run
Reconnect and call modem_agent_get_run with the conversation_id and run_id returned when the run started. Modem continues
accepted runs after the original MCP connection closes.
I connected the wrong organization
Remove or disconnect the Modem MCP server in your client, then authorize again and select the correct organization on the Modem consent screen.