Modem MCP Server

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 search your customer feedback, topics, people, and companies, run the Modem Agent against your connected tools, or update your Modem workspace directly.

This page is about connecting an external MCP client to Modem. To connect external MCP tool servers for the Modem Agent to use, see the External MCP Servers page.

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 three kinds of tools: one that runs the full Modem Agent, one that reads your data directly, and a set that writes to your Modem workspace. 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 current status and, once complete, the agent’s answer.	`conversation_id`, `run_id`
`modem_agent_send_message`	Starts a follow-up turn in an existing MCP conversation.	`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 when the task needs reasoning, multiple steps, or your connected tools, such as Linear, Slack, or GitHub. Agent runs consume credits.

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. Keep checking until the status is completed, failed, or cancelled. 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.

Search your data

Tool	What it does	Scope
`search_modem`	Answers a natural-language question about your Modem data and returns the matching rows.	`data:read`

search_modem is read-only and does not run the full Modem Agent or consume agent credits. Prefer it for lookups and semantic search. It is faster and cheaper than modem_agent_invoke.

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, issue type, keywords, or archived status.
`bulk_update_topics`	Update up to 100 topics at once, such as archiving or re-prioritizing a set.
`merge_topics`	Merge up to 50 source topics into a target topic.
`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 and are marked as destructive, so most MCP clients ask you to confirm each call before it runs.

Write tools apply changes immediately and Modem does not undo them for you. Merges in particular are not reversible from the MCP client, so confirm the target is correct before approving the call.

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. Use search_modem to find the IDs you need before calling a write tool.

Prerequisites

A Modem account with access to the organization you want to use
An MCP client that supports remote Streamable HTTP 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

Use the setup path for your MCP client. 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

In Cursor, 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

Codex can add remote MCP servers from the CLI.

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"

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

ChatGPT connects to remote MCP servers through Developer mode, 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 Modem and enter the server URL https://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
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 search_modem and nothing else.

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. Lookups and questions, which normally route to search_modem: Multi-step work and anything involving connected tools, which normally routes to modem_agent_invoke: Changes to your workspace, which normally route to the write tools: For a new task, include the context the agent needs in the first prompt. To continue a run, ask your client to send a follow-up in 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.	Four agent-run tools and the workspace write tools
`data:read`	Read your Modem data through natural-language search. Does not run the paid agent.	`search_modem`

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 the limit returns a rate-limit error carrying a retryAfter hint your client should back off against. modem_agent_invoke is 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 search_modem 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 for the retryAfter interval in the error and retry with backoff. If modem_agent_invoke is rejected for cost rather than rate, check your organization’s agent credit allowance.

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.

The Modem Agent

Learn what the Modem Agent can query and do.

External MCP Servers

Connect external MCP tool servers for the Modem Agent to use.

Getting Started

Using Modem

Ingest API

Modem MCP Server

Account

Modem MCP Server

Server URL

Tools

Run the agent

How an agent run works

Idempotency keys

Search your data

Write to your workspace

Permissions

Field values

Prerequisites

Set Up Your Client

Claude Code

Cursor

VS Code and GitHub Copilot

Codex

opencode

ChatGPT

Other MCP Clients

Authorize Modem

Example Prompts

Security and Access

Rate limits

Troubleshooting

The Modem Agent

External MCP Servers

​Server URL

​Tools

​Run the agent

​How an agent run works

​Idempotency keys

​Search your data

​Write to your workspace

​Permissions

​Field values

​Prerequisites

​Set Up Your Client

​Claude Code

​Cursor

​VS Code and GitHub Copilot

​Codex

​opencode

​ChatGPT

​Other MCP Clients

​Authorize Modem

​Example Prompts

​Security and Access

​Rate limits

​Troubleshooting

​Related

The Modem Agent

External MCP Servers

Server URL

Tools

Run the agent

How an agent run works

Idempotency keys

Search your data

Write to your workspace

Permissions

Field values

Prerequisites

Set Up Your Client

Claude Code

Cursor

VS Code and GitHub Copilot

Codex

opencode

ChatGPT

Other MCP Clients

Authorize Modem

Example Prompts

Security and Access

Rate limits

Troubleshooting

Related