Remote (URL) Servers

Connecting a remote server

In Apps, go to Connect a server, below Connected Servers, choose Remote (URL) (the alternative is Local (stdio)), and fill the fields:

Then click Connect Server. The server appears under Connected Servers with a status badge, and the screen says what the add found:

• Server connected and saved. — a server that needs no sign-in, or a token that works, connects as it is added, and its tools are listed.
• Saved — still connecting. It will show as connected when it does. — the row turns Connected by itself once the list refreshes.
• Saved, but it did not connect: … with the server's own reason — unreachable, a bad certificate, no answer in time — then Retry once it is reachable. The server stays listed, and Retry connection connects it later.

SynapseOrch connects with the Streamable HTTP transport and falls back to SSE for older servers.

On SynapseOrch Cloud

Cloud's Apps screen adds remote servers only — there is no local (stdio) option. A server added by URL with no token is dialled as it is saved, and the screen says what that found:

• Server added and connected — 12 tools available in the builder.
• Server added, but it did not connect: … with the reason — refused, a bad certificate, no answer in time. The server stays listed, and its pane keeps the reason.

A server added with a token is saved and waits for Discover tools, which dials it and loads its tool list. A server's status reads Connected, Not connected, Authorizing… or Re-authorize.

Preset shortcuts

Remote Presets above the form fills in the label, Unique ID and URL for common services: Vercel, GitHub Copilot, Slack, Notion, Jira, Zapier, Figma and Fetch.

GitHub Copilot asks for a personal access token; the others sign in with OAuth, and Fetch needs no authentication.

A server added from an older version of the Slack, Figma or GitHub Copilot preset may carry that preset's placeholder as its token — SLACK_CLIENT_ID, FIGMA_PERSONAL_ACCESS_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN — and never signs in. Its row says so. Remove it and add it again from its preset: Slack and Figma then sign in with OAuth, GitHub Copilot with your token. The server list never shows a saved token.

Authentication modes

OAuth 2.0

Leave the token field empty. When you click Connect Server, SynapseOrch registers itself with the service's authorisation server — as SynapseOrch, which is the name the sign-in page shows — and opens that page in a popup; you don't create an OAuth app yourself. A server connected before the name changed keeps its old registration, and so shows the old name, until you remove it and connect it again. After you authorise, the popup shows "Connected to …" and closes, and the card changes from Disconnected to Connected. The screen checks for the connection every 5 seconds for a minute; if you finish later, click Refresh.

If the service doesn't produce a sign-in page within 15 seconds, the server is saved as Disconnected — use Retry connection.

The tokens are stored in SynapseOrch's database, one set per server, and deleted when you remove the server. An expired access token is renewed with its refresh token when SynapseOrch connects — at startup, or when you retry or reconnect. If that fails, the card shows Re-Auth.

Bearer token (PAT)

Paste your token into the token field before clicking Connect Server. It is sent as a Bearer header on every request.

Preset remote servers

The presets correspond to the following configurations. You can also enter them by hand if you need to change anything.

The Unique ID is the tool prefix, so the GitHub Copilot preset's tools are named Github__…. Which tools each service offers, and what its token needs, is up to that service — its tools appear in an agent's Tools section once connected.

Advanced: how a remote server is stored

{
  "name": "Jira",
  "label": "Jira",
  "server_type": "remote",
  "url": "https://mcp.atlassian.com/v1/mcp",
  "token": ""
}

OAuth callback

The OAuth redirect URI is http://localhost:8765/api/mcp/oauth/callback, with the port following SYNAPSE_BACKEND_PORT. SynapseOrch registers it with the service automatically.

The host is always localhost. After you authorise, the service sends your browser to that address, so the sign-in has to happen in a browser that reaches the SynapseOrch backend as localhost — on the same machine, or through a tunnel to the backend port. (Google Workspace uses a different callback; see Google Workspace.)

Reconnecting

If a remote server disconnects, use the button on its card:

• Retry connection (Disconnected) or Re-authenticate (Re-Auth) — SynapseOrch first tries the stored OAuth tokens, renewing them if they have expired. Only if that fails does it open the sign-in popup again. A token-based server retries with its token.
• Force reconnect (on hover, Connected) — refreshes a session that has gone stale.

Connection status

Each server card shows one of these badges:

A remote server that could not connect while Synapse was starting — one run beside it in Docker Compose that was not up yet, say — is tried once more as soon as the backend is listening, so it needs no Retry. An OAuth server is retried with its stored tokens only; local (stdio) servers are not retried.

A local server that isn't allowed on this deployment is stored as disabled and not started; see Local (stdio) Servers.