> ## Documentation Index
> Fetch the complete documentation index at: https://modem.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Modem MCP Server

> Search, update, and run the Modem Agent from Claude, ChatGPT, Cursor, and more

export const Prompt = ({text, variant = 'accent'}) => {
  const [copied, setCopied] = useState(false);
  const handleCopy = async () => {
    try {
      await navigator.clipboard.writeText(text);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch {}
  };
  const clipboardIcon = <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <title>Copy</title>
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
        </svg>;
  const checkIcon = <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <title>Copied</title>
            <polyline points="20 6 9 17 4 12" />
        </svg>;
  const promptIcon = <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" style={{
    flexShrink: 0,
    opacity: 0.4
  }}>
            <title>Prompt</title>
            <path d="M20 2H2v20h2V4h16v12H6v2H4v2h2v-2h16V2zM6 7h12v2H6zm8 4H6v2h8z" />
        </svg>;
  return <div className={`prompt prompt-${variant}`} style={{
    marginTop: '12px',
    marginBottom: '12px'
  }}>
            {promptIcon}
            <span className="prompt-text">{text}</span>
            <button className="prompt-copy" onClick={handleCopy} title="Copy to clipboard" type="button">
                {copied ? checkIcon : clipboardIcon}
            </button>
        </div>;
};

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.

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.

<Info>
  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](/docs/integrations/mcp-servers).
</Info>

## 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](https://claude.ai/directory/modem) |
| ChatGPT and Codex | ChatGPT plugin directory | [Install in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6aa301615af48191a59c3febcdef6ec2) |
| Cursor | Cursor Marketplace | [Install in Cursor](https://cursor.com/marketplace/modem) |

<Steps>
  <Step title="Open the listing">Open the Modem listing for your client from the table above.</Step>
  <Step title="Install the plugin">Follow the listing's install flow. In Cursor you can also run `/add-plugin modem`.</Step>
  <Step title="Authorize Modem">Sign in and approve access on the Modem consent screen. See [Authorize Modem](#authorize-modem).</Step>
</Steps>

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](#server-url) and the [client setup steps](#set-up-your-client) below.

## Server URL

Use this URL in your MCP client:

```text theme={null}
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 five kinds of tools: one that runs the full Modem Agent, one that serves skills for using this server, one that reads your data directly, one that reads the Modem docs, 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](#security-and-access).

For every tool's full parameter list, result shape, and example invocations, see the [MCP Tool Reference](/docs/api/mcp-tools).

### 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

<Steps>
  <Step title="Start the run">
    Call `modem_agent_invoke` with a prompt and an `idempotency_key`. Modem returns `conversation_id`, `run_id`, and a `working` status.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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 `search-modem`) 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](/docs/api/mcp-skills) for how that works. `modem_skills` is not the Skills page in the Modem dashboard.

### 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`.

### 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, 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. 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.

<Warning>
  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.
</Warning>

#### 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
* Claude, ChatGPT, Codex, or Cursor to [install a plugin](#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](#install-a-plugin) is quicker. In every case, the server URL is:

```text theme={null}
https://mcp.modem.dev/mcp
```

### Claude Code

Claude Code can add remote HTTP MCP servers from the CLI.

```bash theme={null}
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](https://cursor.com/marketplace/modem) or run `/add-plugin modem` in Cursor.

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=modem\&config=eyJ1cmwiOiJodHRwczovL21jcC5tb2RlbS5kZXYvbWNwIn0%3D)

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.

```json theme={null}
{
    "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.

```json theme={null}
{
    "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](https://chatgpt.com/plugins/plugin_asdk_app_6aa301615af48191a59c3febcdef6ec2) also works in Codex. To add the server from the CLI instead, run:

```bash theme={null}
codex mcp add modem --url https://mcp.modem.dev/mcp
```

Then authorize the server, which opens the browser flow:

```bash theme={null}
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.

```toml theme={null}
[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.

```json theme={null}
{
    "$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:

```bash theme={null}
opencode mcp auth modem
```

### ChatGPT

The quickest path is the [Modem plugin in the ChatGPT plugin directory](https://chatgpt.com/plugins/plugin_asdk_app_6aa301615af48191a59c3febcdef6ec2).

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.

1. 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**.
2. In the apps/connectors list, click the add (**+**) button to create a new connection.
3. Give it a name such as `Modem` and enter the server URL `https://mcp.modem.dev/mcp`.
4. If asked for an authentication type, choose **OAuth**. Create the connection.
5. 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](https://code.claude.com/docs/en/mcp) |
| ChatGPT | [Connect a remote MCP server to ChatGPT](https://developers.openai.com/plugins/deploy/connect-chatgpt) |
| Cursor | [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) |
| VS Code | [MCP configuration reference](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration) |
| Codex | [Codex MCP documentation](https://developers.openai.com/codex/mcp) |
| opencode | [opencode MCP servers](https://opencode.ai/docs/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`, and `search_modem`. `modem_skills` and `modem_docs` 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.

Lookups and questions, which normally route to `search_modem`:

<Prompt text="Search Modem for the topics with the most feedback from enterprise accounts this month." />

<Prompt text="Ask Modem which people are associated with acme.com." />

Multi-step work and anything involving connected tools, which normally routes to `modem_agent_invoke`:

<Prompt text="Use Modem to summarize the highest-priority bug reports from the last 7 days." />

<Prompt text="Ask Modem which customers requested SSO and whether any related Linear issues already exist." />

<Prompt text="Continue that Modem conversation and check which affected customers are on annual plans." />

Changes to your workspace, which normally route to the write tools:

<Prompt text="In Modem, archive every topic about the old billing page and tell me which ones you archived." />

<Prompt text="Find the duplicate Acme companies in Modem and merge them into the one with the acme.com domain." />

<Prompt text="Mark the topic about SSO login failures as high priority in Modem." />

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. | `modem_skills`, `modem_docs`, four agent-run tools and the workspace write tools |
| `data:read` | Read your Modem data through natural-language search, and load skills for this server. Does not run the paid agent. | `modem_skills`, `modem_docs`, `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 it returns a rate-limit error; wait about a minute and retry with backoff. `modem_agent_invoke` and `modem_agent_send_message` are additionally subject to your organization's agent credit limits.

## Troubleshooting

<AccordionGroup>
  <Accordion title="My MCP client does not show the Modem tools">
    <ul>
      <li>Confirm the server URL is exactly `https://mcp.modem.dev/mcp`.</li>
      <li>Restart the client or reload its MCP server list.</li>
      <li>Make sure your client supports remote Streamable HTTP MCP servers with OAuth.</li>
    </ul>
  </Accordion>

  <Accordion title="Some tools are missing but others work">
    Tools are exposed by scope. If you see `modem_skills`, `modem_docs`, and `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.
  </Accordion>

  <Accordion title="Authorization fails or returns unauthorized">
    <ul>
      <li>Sign in with the Modem account that belongs to the organization you selected.</li>
      <li>Re-run the OAuth flow and approve the requested permissions.</li>
      <li>If authorization still fails, contact Modem support.</li>
    </ul>
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Skills for MCP Clients" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/code.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=6c9b5cbb0e89aebc55e9fd769945fc07" href="/docs/api/mcp-skills" width="24" height="24" data-path="icons/code.svg">
    The skills the server gives your MCP client, and how the client finds them.
  </Card>

  <Card title="The Modem Agent" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/bot-bolt.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=dda761a2f7042ebc27c668cc644df76c" href="/docs/features/agent" width="22" height="22" data-path="icons/bot-bolt.svg">
    Learn what the Modem Agent can query and do.
  </Card>

  <Card title="External MCP Servers" icon="https://mintcdn.com/modem-844d7a4a/Wr2r4IRr97lNQiQb/icons/link.svg?fit=max&auto=format&n=Wr2r4IRr97lNQiQb&q=85&s=e774d33588635d44c6c935b78ed55f13" href="/docs/integrations/mcp-servers" width="24" height="24" data-path="icons/link.svg">
    Connect external MCP tool servers for the Modem Agent to use.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.