# Remote MCP Servers


The Remote MCP integration connects an MCP client on your VM (Claude Code,
Codex, Shelley or your own code) to a remote [Model Context
Protocol](https://modelcontextprotocol.io/) server that speaks the
Streamable HTTP transport. exe.dev stores any credentials outside the VM
and adds a token to upstream requests when needed. Configure the VM's MCP
client with the integration's URL and no authentication.

There are three ways to connect:

- **Sign-in.** Some servers (Notion's, for example) let you sign in with your
  account on the provider's own page. exe.dev keeps the sign-in and adds its
  access token to requests. It does not send the refresh token to the VM.
- **Token.** Paste a token or API key that the server accepts as
  `Authorization: Bearer <token>`. Keys that require a different header
  are not supported.
- **None.** Public servers (DeepWiki's, for example) need no credentials, and
  some refuse requests that carry any. exe.dev sends none.

However the integration authenticates, a VM uses it the same way.

## What an attached VM can do

An attached VM can call any tool the server makes available to the account
or token, including tools that create, change or delete data. Optional
[step-up approval](/docs/integrations-step-up) requires you to approve the VM
before it can use the integration. exe.dev does not filter, approve or
rewrite individual tool calls. Use the least privileged account or token
the provider offers, attach only to VMs that need it, and limit which tools
your MCP client uses (see below).

For a sign-in, exe.dev requests the permissions named in the server's
challenge or, if none are named there, in its resource metadata. It adds
`offline_access` if the authorization server offers it, so the sign-in can
be renewed. The dialog shows the permissions requested, if any. After
sign-in, the integration row shows what the provider reported granting,
or what exe.dev requested if the provider didn't say. The provider's consent
screen is the authority on what you grant; exe.dev can't narrow it.

## Step 1: create the integration

You need the server's complete HTTPS endpoint URL, for example
`https://mcp.notion.com/mcp`.

On the [Integrations page](/integrations), open **Remote MCP server** from
the catalog, enter the endpoint and choose **Check server**. exe.dev tries
`server/discover` (or `initialize` for older servers) and checks `tools/list`
if that succeeds.

- If exe.dev can sign in, choose **Continue to _host_** and approve on the
  provider's page. exe.dev checks the new sign-in before adding the
  integration and returning you to the catalog.
- If the check passes without credentials, choose **Add integration** or
  **Use a token instead**.
- If the dialog asks for a token, enter one the server accepts. This
  includes servers whose sign-in requires an app registered in advance.
  An unexpected server response can also lead to the token prompt.
  Double-check the endpoint if you expected sign-in or no credentials.

Via SSH, leave out `--token` to sign in:

```
exe.dev ▶ integrations add remote-mcp --name notion --base-url=https://mcp.notion.com/mcp --attach vm:my-vm
...
Open this URL in your browser to sign in:
  https://exe.dev/remote-mcp/signin?state=...
```

Open the link as the same exe.dev user and leave the SSH session open while
you sign in. The terminal waits up to 10 minutes. Or pass `--token=-` to
prompt for a token in the terminal or read it from stdin:

```
exe.dev ▶ integrations add remote-mcp --name github-mcp --base-url=https://api.githubcopilot.com/mcp/ --token=- --attach vm:my-vm
token:
```

For a server that needs no credentials, pass `--no-auth`. exe.dev adds it
only if the check passes without credentials, unless you pass
`--skip-verify`:

```
exe.dev ▶ integrations add remote-mcp --name deepwiki --base-url=https://mcp.deepwiki.com/mcp --no-auth --attach vm:my-vm
```

Use an HTTPS URL with a public DNS hostname, not an IP address. URLs with
embedded credentials, escaped paths, query parameters or fragments are
not supported. If the server redirects, use the final URL.

## Step 2: point your MCP client at it

Whatever path the server's endpoint has, attached VMs always use the `/mcp`
path on the integration host (`/mcp/` works too). Substitute the hostname
shown when you created the integration: `<name>.int.exe.xyz` for a personal
integration or `<name>.team.exe.xyz` for a team integration.

```
https://notion.int.exe.xyz/mcp
```

Configure it as a Streamable HTTP server with no authentication. Your
client still needs to support the upstream server's protocol version.

- Claude Code: `claude mcp add --transport http notion https://notion.int.exe.xyz/mcp`
- Codex: in `~/.codex/config.toml`, `[mcp_servers.notion]` with
  `url = "https://notion.int.exe.xyz/mcp"`. For headless runs, approve only
  the tools you trust to run without a prompt, for example with
  `[mcp_servers.notion.tools.<tool-name>]` and `approval_mode = "approve"`.
- OpenCode: `opencode mcp add notion --url https://notion.int.exe.xyz/mcp`
- Crush: `"mcp": {"notion": {"type": "http", "url": "https://notion.int.exe.xyz/mcp"}}`
- Goose: `goose session --with-streamable-http-extension https://notion.int.exe.xyz/mcp`
- Cline: `{"mcpServers": {"notion": {"type": "streamableHttp", "url": "https://notion.int.exe.xyz/mcp"}}}`
- Kimi Code: `~/.kimi-code/mcp.json` with `{"mcpServers": {"notion": {"url": "https://notion.int.exe.xyz/mcp"}}}`
- Pi: `pi mcp add notion --url https://notion.int.exe.xyz/mcp`
- MCP SDKs and frameworks need no credentials: FastMCP (Python) `Client(url)`,
  TypeScript `new StreamableHTTPClientTransport(new URL(url))`, Go
  `&mcp.StreamableClientTransport{Endpoint: url}`, OpenAI Agents
  `MCPServerStreamableHttp(params={"url": url})`, Pydantic AI
  `MCPToolset(url)`, LangChain `{"transport": "streamable_http", "url": url}`,
  Mastra `{url: new URL(url)}`, smolagents and CrewAI
  `{"url": url, "transport": "streamable-http"}`.
- MCP Inspector: `npx @modelcontextprotocol/inspector --cli https://notion.int.exe.xyz/mcp --method tools/list`

To limit which tools the client can use, see Claude Code's `permissions.deny`,
Codex and Crush's `enabled_tools`, Goose's `available_tools`, OpenCode's
`permissions`, the OpenAI Agents SDK's `create_static_tool_filter`, or
Pydantic AI's `.filtered()`.

To check tool access, list tools from the VM with a client that supports the
server's protocol version. For a server that supports the older
`initialize` handshake, this checks that the endpoint responds without
listing tools:

```
curl -si https://notion.int.exe.xyz/mcp -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```

## What exe.dev forwards

exe.dev forwards `POST` requests and session-ending `DELETE` requests to the
configured server endpoint. The `POST` body is sent unchanged, up to 4 MiB
(`413` if larger); `DELETE` bodies are dropped. Query parameters are not
supported (`400`).

Of the VM's headers, exe.dev forwards only `MCP-Protocol-Version`,
`Mcp-Session-Id`, `Mcp-Method`, `Mcp-Name`, `Mcp-Param-*` and `User-Agent`.
It sets `Content-Type` to `application/json` on `POST` and `Accept` to
`application/json, text/event-stream`. It adds the integration's bearer
token if it has one.

exe.dev passes through the server's status, selected response headers and
body, including event streams. It replaces known token values with
`[redacted]`. Only connect to servers you trust with the credential.
Redirects instead return `502`; configure the final URL.

Once the VM is allowed to use the integration, `GET` on `/mcp` returns
`405 Method Not Allowed`: there is no standalone event stream. Paths other
than `/mcp` and `/mcp/` return `404`, including OAuth discovery paths.

exe.dev strips the server's sign-in challenge (`WWW-Authenticate`); the VM
does not sign in to the provider. If your stored token expires or is
revoked, the VM gets the server's error. Rotate the token:

```
exe.dev ▶ integrations edit github-mcp --token=-
```

Changing the endpoint with `--base-url` also requires the token, so a stored
token can't be sent to a different server.

## Signed-in integrations

### Keeping it working

exe.dev keeps the sign-in's refresh token and its current access token.
It does not renew them on a schedule. If the server returns `401`, exe.dev
first looks for a token another request already renewed. Otherwise, it
checks the token with its own discovery and tool-listing requests. If that
check also gets `401`, exe.dev renews the sign-in and saves the new tokens.
It retries the VM's request once with the replacement token. If the check
succeeds or is inconclusive (for example, it gets `403` or times out), the
VM gets the original `401` without the sign-in challenge.

Attached VMs share the same access token and any provider limits tied to
it. If the provider ties an MCP session to the previous token, it may
return `404` for that session after renewal; the client should start a new
session. If you get `503` with `Retry-After` during renewal, wait the stated
delay and retry. If renewal is temporarily unavailable, the gateway can
return `502`; try again.

If exe.dev determines it can't renew the sign-in, for example because
you revoked it at the provider, the catalog marks the integration **Needs
reconnect**. Requests then return `401 reconnect_required`. Choose
**Reconnect** or run the command below to sign in again without changing
the name or attachments:

```
exe.dev ▶ integrations edit notion --reconnect
```

A signed-in integration is tied to its endpoint; to use another endpoint,
add a new integration. Sign-in integrations are personal (they act as your
account), so team integrations use a token, or none for a server that needs
none. exe.dev cannot save a sign-in if the provider doesn't issue a refresh
token.

Removing a signed-in integration deletes exe.dev's copy of the sign-in and,
when the provider offers revocation, asks the provider to revoke it (the
refresh token and the access token exe.dev holds); whether
it does is up to the provider. `integrations remove` says what happened.
exe.dev skips the request when another of your integrations signed in to the
same provider through the same exe.dev app, because some providers revoke
every sign-in of that app at once. Access tokens the provider already issued
may keep working until they expire. Where exe.dev cannot revoke, remove
exe.dev's access in your account settings with the provider. Deleting your
exe.dev account removes all your sign-ins and asks providers that support
revocation to revoke them.

## Integrations without credentials

An integration added with `--no-auth` sends no `Authorization` header at all.
It can be a personal or a team integration (`--team`). It has nothing to
rotate or reconnect; to use a token or another endpoint, add a new
integration. `integrations test <name>` checks that the server
still answers without credentials.
