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

# External MCP Servers

> Connect external tool servers so the Modem Agent can use custom tools

The External MCP Servers integration lets you connect external [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) servers to Modem. Once connected, the Modem Agent can discover and use tools from those servers alongside its built-in capabilities.

## Prerequisites

* Membership in your Modem organization. Any member can add a personal server; **Admin or Owner** access is required to add an organization server.
* An MCP-compatible server with a publicly accessible HTTPS endpoint

## Setup

<Steps>
  <Step title="Open External MCPs settings">
    Go to **Settings** → **External MCPs** in your Modem dashboard.
  </Step>

  <Step title="Add a server">
    Click **Add personal MCP** or **Add organization MCP**. Choose the server's [Visibility](#visibility), then enter a name and server URL.
    Modem generates the slug used for tool namespacing from the name.

    <Info>
      The URL must use HTTPS. Localhost, private IP addresses, and `.local` domains are not allowed.
    </Info>
  </Step>

  <Step title="Choose a transport type">
    Select the transport protocol your server uses:

    * **HTTP (Streamable)**: The default for most MCP servers.
    * **SSE (Legacy)**: For older servers that use Server-Sent Events.
  </Step>

  <Step title="Configure authentication">
    Choose the authentication method your server requires. See [Authentication](#authentication) below.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection** to verify Modem can reach your server and discover its tools. If the test passes, you'll see a list of available tools.
  </Step>

  <Step title="Save">
    Click **Save**. The server's tools are now available to the Modem Agent.
  </Step>
</Steps>

## Authentication

MCP servers support four authentication methods:

### None

No authentication. Use this for servers that handle auth at the network level or don't require it.

### Bearer Token

Modem sends an `Authorization: Bearer <token>` header with every request. Enter your token during setup. It's encrypted at rest and never exposed in API responses.

### Custom Headers

Define one or more custom HTTP headers that Modem sends with every request. Use this for API key headers, custom auth schemes, or any other header-based authentication your server expects.

### OAuth 2.1

For MCP servers that use OAuth authorization. Modem handles token storage and automatic refresh. The server's visibility determines whose account it uses.

#### Setup

<Steps>
  <Step title="Create the connection">
    Select **OAuth 2.1** as the authentication method. If your server does not support [Dynamic Client
    Registration](https://datatracker.ietf.org/doc/html/rfc7591), enter the **Client ID** and **Client Secret** provided by the server.
    Both are encrypted at rest and never exposed in API responses. Click **Save**.
  </Step>

  <Step title="Connect your account">
    After saving, open the server and click **Connect your account** in the **Visibility** card. You'll be redirected to the server's
    authorization page.
  </Step>

  <Step title="Authorize">
    Approve access on the server's authorization page. You'll be redirected back to Modem, and your connection status will show as
    connected.
  </Step>
</Steps>

<Info>
  An **Organization** server uses the most recently connected member's account for everyone. Any member can connect their account to
  restore access when it expires. For a **Personal** server, only the owner connects their own account. See [Visibility](#visibility).
</Info>

#### How it works

Modem uses the **Authorization Code flow with PKCE** (Proof Key for Code Exchange) for enhanced security. When you click "Connect your account," Modem:

1. Discovers the server's OAuth endpoints via `/.well-known/oauth-authorization-server`
2. Registers as a client automatically if the server supports Dynamic Client Registration
3. Redirects you to authorize with a PKCE challenge
4. Exchanges the authorization code for access and refresh tokens

Access tokens are encrypted at rest. When a token is close to expiring, Modem automatically refreshes it using the refresh token. If a refresh token is not available, you'll need to reconnect manually.

#### Managing connections

For organization servers, the **Visibility** card shows **Connected by** with the member whose account is in use. If that account's token expires and cannot be refreshed, any member can click **Reconnect** to authorize their own account for everyone.

For personal servers, the card shows your account's status. Click **Reconnect** if your token expires, or **Disconnect** to remove your authorization.

## Visibility

Every server has a **Visibility** setting, regardless of authentication method:

| Visibility | Owner | Who can use it | Who can view and manage it | Who can create it |
| - | - | - | - | - |
| **Organization** | The organization | Every member, every automation, and system runs | Any member can view; Admins and Owners manage | Admin or Owner |
| **Personal** | The member who added it | Only the owner, in chat and through the [Modem MCP Server](/docs/api/modem-mcp-server); never in automations | Only the owner; admins see a limited, read-only listing | Any member |

Admins can see another member's personal server's name, owner, authentication type, and enabled status in the list. They cannot open it, view its URL or tools, use its credentials, edit it, or delete it. Other members do not see it at all.

Only the member who added a server can change its visibility, and they must be an Admin or Owner. Making a personal server an organization server gives everyone access through its stored credentials or connected account, and lets admins manage it.

Making an organization server personal removes other members' connected accounts; they can add their own personal server to keep using it.

## How Tools Appear to the Agent

When you connect an MCP server, the agent discovers its tools automatically at the start of each conversation.

* **Namespacing.** Tools are prefixed with the server's slug to avoid name collisions. For example, a tool called `search` on a server with slug `my-server` becomes `ext_my-server_search`.
* **Approval in chat.** External tools require confirmation by default. The agent describes what it wants to do and waits for approval. Tools the server marks read-only (`readOnlyHint`) and not destructive skip the prompt, and so does every tool on a server with **Never require approval** enabled.
* **Tool descriptions.** Descriptions from your server are passed through to the agent (truncated to 500 characters).

<Warning>
  Personal servers are not available to automations, including the owner's own automations. Use an organization server for automations.
  Headless automation runs execute tools without approval prompts.
</Warning>

## Enabling and Disabling Servers

You can disable an entire server without deleting it by toggling it off. Disabled servers are skipped during tool discovery.

## Permissions

| Action | Required Role |
| - | - |
| View organization servers and tools | Any member |
| View personal servers and tools | Its owner |
| Add a personal server | Any member |
| Add, edit, or remove organization servers | Admin or Owner |
| Edit or remove a personal server | Its owner |
| Test connections | Any member (own inline config or servers they can manage) |
| Connect/disconnect own OAuth account | Any member for organization servers; its owner for personal servers |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection test fails">
    * Verify your server URL is correct and uses HTTPS
    * Check that the server is publicly accessible (not behind a VPN or firewall)
    * Confirm your authentication credentials are correct
    * Make sure the server responds within 15 seconds
  </Accordion>

  <Accordion title="Tools aren't appearing in the agent">
    * Run **Test Connection** to verify tool discovery works
    * Check that the server is enabled
    * Verify the server hasn't been disabled
  </Accordion>

  <Accordion title="Agent responses are slow after adding a server">
    Tool discovery reads a cached copy of each server's tool list, so a slow server does not delay the start of a conversation. When a conversation starts and the cached list is more than an hour old, Modem refreshes it in the background, so changes to your server's tools show up in a later conversation. Modem connects to your server when the agent calls one of its tools, with a 10-second connection timeout and a 90-second limit per attempt. Tools with `query` in their name are retried up to twice after a timeout, so a slow query can take up to about 4.5 minutes before it fails.

    * Check how long your server takes to answer tool calls
    * Disable servers you're not actively using
  </Accordion>

  <Accordion title="Tools fail when the agent tries to use them">
    * Check your server logs for errors
    * Verify the server is still running and accessible
    * Confirm authentication credentials haven't expired or been rotated
    * Try running **Test Connection** again to see if the server is reachable
  </Accordion>

  <Accordion title="OAuth connection fails or redirects to an error page">
    * Verify the server's `/.well-known/oauth-authorization-server` endpoint is accessible
    * If not using Dynamic Client Registration, confirm the Client ID and Client Secret are correct
    * If the error says the server rejected Modem's redirect URI, ask its operator to allowlist `https://app.modem.dev/mcp/oauth/callback`, or delete the server and add it again with a Client ID for that URL. Add the Client Secret if the server issued one
    * Check that the server's authorization endpoint uses HTTPS
    * Make sure you completed the authorization within 15 minutes (the state cookie expires after that)
  </Accordion>

  <Accordion title="OAuth token expired and tools stopped working">
    If the server issued a refresh token, Modem refreshes it automatically. If refresh fails or no refresh token was provided:

    * Open the server and click **Reconnect** in the **Visibility** card to re-authorize
    * Check the server's logs for token revocation or refresh errors
  </Accordion>
</AccordionGroup>

## Removing a Server

To remove an MCP server:

1. Go to **Settings** → **External MCPs**
2. Open the row menu (**⋮**) for the server you want to remove and choose **Delete**
3. Confirm the deletion

If you want to temporarily stop the agent from using a server without deleting it, disable the server instead. Disabled servers keep their configuration but are skipped during tool discovery.


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