Add MCP servers to the SynapseX CLI

This page connects a Model Context Protocol (MCP) server to the SynapseX CLI. At the end you will have a server registered, confirmed in mcp list, and its tools available to the agent on your next prompt.

In one sentence: registering an MCP server gives the agent the tools that server exposes, so it can work directly with your own systems instead of only with the tools that ship in the box.

Check what is registered


synapsex-code mcp list

On a clean install:


No MCP servers configured
Add servers with: synapsexCode mcp add

mcp ls is an alias for the same command.

Add a local server (a command)

Put the server’s command after --:


synapsex-code mcp add my-tools -- /path/to/your-mcp-server --stdio

Pass environment variables with a repeatable --env KEY=VALUE:


synapsex-code mcp add my-tools \
  --env SERVICE_URL=https://internal.example.com \
  --env SERVICE_TOKEN=YOUR_SERVICE_TOKEN \
  -- /path/to/your-mcp-server --stdio

--env is local-only. Passing it alongside --url fails with --env is only valid for local MCP servers.

Add a remote server (a URL)


synapsex-code mcp add my-remote --url https://mcp.example.com/mcp

Pass HTTP headers with a repeatable --header KEY=VALUE:


synapsex-code mcp add my-remote \
  --url https://mcp.example.com/mcp \
  --header Authorization="Bearer YOUR_MCP_TOKEN"

--header is remote-only. Passing it to a local server fails with --header is only valid for remote MCP servers.

Exactly one of --url or a command after -- is required. Give both, or neither, and the CLI stops with Provide either --url <url> or a command after --. Each --env / --header value must be KEY=VALUE.

A complete example, end to end


# 1. Nothing registered yet
synapsex-code mcp list
# → No MCP servers configured
 
# 2. Register a local stdio server
synapsex-code mcp add my-tools -- /path/to/your-mcp-server --stdio
# → MCP server "my-tools" added to /Users/you/.config/synapsexCode/synapsexCode.json
 
# 3. Confirm it is registered and see its status
synapsex-code mcp list
 
# 4. Use it — ask for something only that server's tools can answer
synapsex-code run "use the my-tools server to list the records it exposes"

Replace /path/to/your-mcp-server --stdio with whatever command starts your own MCP server over stdio. Step 4 needs a signed-in provider; see Sign the CLI in to your SynapseX account.

Manage registered servers

Command	What it does
`synapsex-code mcp list`	List servers and their status (alias `mcp ls`)
`synapsex-code mcp auth [name]`	Authenticate with an OAuth-enabled MCP server
`synapsex-code mcp logout [name]`	Remove stored OAuth credentials for a server
`synapsex-code mcp debug <name>`	Debug the OAuth connection for a remote server

mcp auth, mcp logout and mcp debug apply to remote servers. mcp debug refuses a local server, and mcp auth refuses a remote server that is not OAuth-capable.

Where is the configuration written?

The success line prints the exact file, so you never have to guess:


MCP server "my-tools" added to /Users/you/.config/synapsexCode/synapsexCode.json

Run non-interactively (with a name and --url or a command), and the server is written to your global config directory.
Run synapsex-code mcp add with no arguments inside a git project, and the CLI asks first whether to store it in the current project or globally, showing you both paths before you choose.

Project configuration lives in synapsexCode.json / synapsexCode.jsonc or a .synapsexCode/ directory, discovered by walking up from your working directory. Full details: CLI configuration.

Full flag list

Every mcp subcommand and flag: CLI commands.