Synapse as an MCP Server

Synapse is an MCP server. A client holding an API key can run agents and workflows, build them, answer the questions they ask and read the results — and every workflow is also a tool of its own. A delete takes two calls, so nothing goes by accident.

This page is about Synapse serving MCP. For Synapse using other MCP servers as tools, see Apps (MCP servers).

The endpoint

It speaks MCP's streamable HTTP transport, statelessly, with the key as a Bearer token. It takes POST only; anything else is a 405.

On a self-hosted install, Settings → API keys → View docs opens the API reference, whose Connect Claude Code or Cursor (MCP) section shows these snippets with your address filled in.

Claude Code

claude mcp add --transport http synapse http://localhost:3000/api/v1/mcp \
  --header "Authorization: Bearer sk-syn-..."

Cursor

In ~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "synapse": {
      "url": "http://localhost:3000/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk-syn-..." }
    }
  }
}

Clients that start local servers only

A client that can only launch a local (stdio) server runs synapse mcp, which relays stdio to the endpoint. On the machine Synapse is installed on it uses the CLI's own key; elsewhere, set SYNAPSE_API_URL (the origin — the relay adds /api/v1/mcp) and SYNAPSE_API_KEY:

{
  "mcpServers": {
    "synapse": { "command": "synapse", "args": ["mcp"] }
  }
}

The tools

The tool list follows the caller's role. A viewer is offered tools that read; an approver may also answer what waits for a person; a builder builds, runs and deletes. A self-hosted key acts as the install's owner, so it gets every tool. On SynapseOrch Cloud a key reads and runs, and builds and deletes only if it was made with Can also build (see What a key can do); members, billing, keys, provider keys and settings stay in the app. tools/list shows exactly what a key or connection is offered.

update_orchestration sets only the fields it declares, on the workflow it names: another field — an id that is not its own, rubric_id, is_active — is refused by name, and nothing is saved.

Every tool says whether it only reads. The ones that replace what is already there — update_orchestration (every step), remove_step, and create_http_tool or create_skill over one of the same name — and the deletes are marked destructive, so a client such as Claude Code asks before calling them. None reads or writes variables, whose values are often tokens.

A delete takes two calls. The first answers needs_confirmation, with a preview of what would go and a confirm_token; the same call again with that token deletes. A token works once, for ten minutes, for the same tool and arguments, and only for whoever asked. A delete something still uses is refused at the preview, with what uses it. On Cloud, builds and deletes over MCP are in the audit log as the person, with metadata.via set to mcp.

Knowledge

While Knowledge is on, search_knowledge searches every active base, or the one kb names by id or name (Name (kb_…) works too, by its id); a workspace with more than 10 bases must name one. It takes the same filters as the API, as a JSON string, returns up to 20 passages labelled for this result alone, and marks them as untrusted content. list_knowledge_bases lists the bases with their descriptions. On SynapseOrch Cloud a search counts toward the key's 120 searches a minute.

Workflows offered as tools

A workflow becomes a tool of its own only when its Workflow settings → MCP clients → Offer to MCP clients is on (off by default): Claude and other apps connected over MCP see this workflow as a tool of its own, with its inputs. It is served as run_ plus its name — "Weekly client summary" is run_weekly_client_summary — described in its own words, so a client's model finds it by what it does. Its arguments are message and the workflow's declared inputs: the state schema keys that have a description and that no step writes.

Every workflow, offered or not, runs through run_orchestration by its id or exact name. The list is built each time a client lists tools, so a workflow offered during a session appears when the client lists them again.

Running and answering

run_orchestration, a run_<name> tool and answer_run wait up to wait_seconds (default 30, at most 120) for the run to finish or ask a question, and return its status:

• completed, with its response;
• paused, with the question in human_input_required — answer it with answer_run, as text or as an object keyed by the question's field names; an approval takes {"approve": true} or {"approve": false}. A Team step can ask several questions at once: get_run lists them, each with its id, and answer_run takes question_id;
• failed;
• running, when the wait ran out. The run carries on either way; get_run picks it up again, and takes a wait_seconds of its own.

A run is answered once: a second answer is refused. A paused run that has already been answered reads resuming until the answer is taken up.

chat_with_agent sends one message to an agent and returns its reply, waiting up to 120 seconds by default (at most 600). Pass back its session_id to continue the conversation. Its answer carries citations and unresolved_citations, as /api/v1/chat does. An agent that needs a tool call approved stops with awaiting_approval; answer_tool_approval answers it, or a schedule's held call, by its session_id or schedule_id. list_waiting lists everything that waits on a person, each item naming the tool and ids that answer it.

Runs and chats spend model credits, as they do anywhere else.

What is refused

• Synapse AI's own agents and workflow are not served, and neither are its runs.
• inputs keys that start with _ are the engine's own and are refused.
• update_agent cannot turn an agent into one of Synapse AI's own.

Protocol version

The server speaks MCP protocol revisions up to 2025-11-25. A client that prefers 2026-07-28 opens with one probe the server answers 400, then negotiates 2025-11-25 and carries on — one 400 per session in the server's log is expected.

On SynapseOrch Cloud

• Any valid key gets every tool.
• Credits and the key's start limit apply: each run, answer or chat turn counts as a start, and a 429 carries Retry-After.
• A run started beyond your plan's runs at once waits in line: when the wait runs out it reads queued, with its queue_position. The Free plan runs one workflow at a time.
• Apps an owner or admin connects with OAuth see only the tools they were granted.