MCP Server Setup

Two ways to connect: Streamable HTTP (zero install, remote) or the mcp-remote stdio bridge for clients that require it. Both reach the same 13-tool surface.

Prerequisites

  • ▸A Synapse Layer account at forge.synapselayer.org
  • ▸A Connect Token (sk_connect_*) from Dashboard → Connect
  • ▸For the stdio bridge: Node.js 18+ — the mcp-remote bridge runs via npx

Remote (Streamable HTTP)

No local installation required. Point your MCP client to the hosted endpoint:

json
{
  "mcpServers": {
    "synapse-layer": {
      "url": "https://forge.synapselayer.org/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "x-connect-token": "sk_connect_your_token"
      }
    }
  }
}

Note

Streamable HTTP is the recommended transport for most use cases. It requires no local Python installation and connects directly to the Forge infrastructure.

stdio bridge (mcp-remote)

Some hosts (Claude Desktop among them) cannot send custom auth headers on a remote connection. For those, use the mcp-remote bridge — a local stdio process that proxies to the remote endpoint:

json
{
  "mcpServers": {
    "synapse-layer": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://forge.synapselayer.org/api/mcp",
        "--header",
        "x-connect-token: sk_connect_YOUR_TOKEN"
      ]
    }
  }
}

The first run downloads mcp-remote from npm. There is no local server to install — the bridge talks to the same hosted endpoint.

Environment Variables

VariableRequiredDescription
SYNAPSE_TOKENNoRead by the Python SDK when token= is omitted (Synapse()). Connect token (sk_connect_*)

Verify Connection

After configuring your MCP client, ask the agent to run health_check. A successful response confirms the connection:

json
{
  "status": "healthy",
  "version": "2.4.x",
  "engine": "synapse-memory",
  "user_id": "your-tenant-id"
}