Connect an AI client over MCP

SynapseOrch is an MCP server. Any MCP client — Claude Code, Cursor, an agent you wrote — can connect to your workspace and use it: list its agents and workflows, run them, answer them when they stop for a person, search its knowledge bases, chat with its agents, and build. Every workflow is also a tool of its own, named after it, so a client's model finds it by what it does.

Harbor & Pine's operations lead works in Claude Code. Asked to triage invoice INV-1102 from Bayline Packaging, Claude Code calls run_invoice_triage; the run stops for accounts payable's approval, Claude Code asks, and answers the run with the decision. This guide sets that up.

1. Get a key

A client connects with an API key, which acts for the whole workspace. On SynapseOrch Cloud an owner or admin makes one in Settings → Developer — see Get a key. A Cloud key runs; tick Can also build when you make it if the client should build and delete too. On a self-hosted install, it is Settings → API keys, or synapse api-keys generate claude-code in a terminal. The key, sk-syn- and 32 characters, is shown once.

2. Connect your client

It speaks MCP's streamable HTTP transport, with the key as a Bearer token.

claude mcp add --transport http synapse https://api.synapseorch.com/api/v1/mcp \
  --header "Authorization: Bearer $SYNAPSE_API_KEY"

{
  "mcpServers": {
    "synapse": {
      "url": "https://api.synapseorch.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk-syn-..." }
    }
  }
}

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

3. See what it can do

The tools come in four groups:

Tools that replace what is there — update_orchestration, remove_step — and the deletes are marked destructive, so a client such as Claude Code asks before calling them. A delete takes two calls: the first shows what would go, and the second, with its confirm_token, deletes. See MCP server.

Each workflow's tool takes message and wait_seconds, plus the workflow's declared inputs: the state keys that have a description and that no step writes. Harbor & Pine's four:

So the description you give a state key is what the client's model reads. The list is rebuilt each time the client lists tools; a workflow made since then is reached with run_orchestration and its id.

4. Run a workflow, and answer it

{
  "message": "Triage this invoice",
  "invoice": {"number": "INV-1102", "supplier": "Bayline Packaging", "currency": "USD",
              "lines": [{"sku": "BP-BOX-M", "qty": 5000, "unit_price": 1.12}]}
}

{"run_id": "…", "answer": {"approved": true, "comment": "Bulk order agreed with Bayline in September."}}

Answers to questions with no fields are text. An approval with no fields of its own takes {"approve": true} or {"approve": false}.

5. Search, and chat with an agent

• search_knowledge searches every base, or the one kb names — by name, by id, or in the Name (kb_…) form list_knowledge_bases shows — with a filter as a JSON string. It returns up to 20 passages, labelled and marked as untrusted content.
• chat_with_agent sends one message to an agent, named by id or exact name — {"agent": "Order desk", "message": "Who should we notify after a data breach?"} — and returns its reply with citations, waiting up to 120 seconds by default. Pass back its session_id to carry on the conversation.

Limits on SynapseOrch Cloud

Any valid key gets every tool. A key may make 300 requests a minute and the workspace 1,200; starting work — a run, an answer, a chat turn — has its own limit of 60 a minute per key, and searches 120. Above any of them the answer is 429 with Retry-After. A run beyond the plan's runs at once waits in line and reads queued, with its queue_position; runs and chats spend credits and model wallet as they do anywhere else.

Go further

• Synapse as an MCP server — every tool, what is refused, protocol versions
• The public API — the same runs over plain HTTP, with webhooks
• API Keys and the Developer Page — what a key can do, and revoking it
• MCP servers — the other direction: apps' tools for your agents, from their MCP servers