Skip to main content
The External MCP Servers integration lets you connect external Model Context Protocol (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

1

Open External MCPs settings

Go to Settings → External MCPs in your Modem dashboard.
2

Add a server

Click Add personal MCP or Add organization MCP. Choose the server’s Visibility, then enter a name and server URL. Modem generates the slug used for tool namespacing from the name.
The URL must use HTTPS. Localhost, private IP addresses, and .local domains are not allowed.
3

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

Configure authentication

Choose the authentication method your server requires. See Authentication below.
5

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

Save

Click Save. The server’s tools are now available to the Modem Agent.

​
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

1

Create the connection

Select OAuth 2.1 as the authentication method. If your server does not support Dynamic Client Registration, enter the Client ID and Client Secret provided by the server. Both are encrypted at rest and never exposed in API responses. Click Save.
2

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

Authorize

Approve access on the server’s authorization page. You’ll be redirected back to Modem, and your connection status will show as connected.
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.

​
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: 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).
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.

​
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

​
Troubleshooting

  • 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
  • Run Test Connection to verify tool discovery works
  • Check that the server is enabled
  • Verify the server hasn’t been disabled
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
  • 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
  • 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)
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

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