SynthBoard MCP help center

1. 1
   Create an API key

   Open the Control Center → API Keys and click Create key. The key is shown exactly once — copy it somewhere safe.
2. 2
   Paste into your client config

   Pick your client below. Each has a dedicated config file — paste the snippet and replace sb_live_... with your real key.
3. 3
   Restart the client

   Quit fully and reopen. The SynthBoard tools + prompts should appear in the client's tool menu.
4. 4
   Try a prompt

   Type /synthboard-boardroom and ask a real strategic question. The decision brief staffs the board; the board debates and delivers a memo.

Ask a real strategic question. Your agent calls synthboard.session.plan, shows you the proposal, then starts the run. No synth-picking needed — an adaptive decision brief reads the question and staffs the right advisors.

// 1. Plan — nothing charged yet
{ "name": "synthboard.session.plan",
  "arguments": {
    "question": "Should we launch a free tier next quarter?",
    "session_type": "boardroom",
    "mode": "decision"
  } }
// → { plan_id, proposal, estimated_credits, expires_at }

// 2. Start with the approved plan
{ "name": "synthboard.session.start",
  "arguments": { "plan_id": "<plan_id>" } }
// → { session_id, task_id, session_type: "boardroom", session_url }

// 3. Wait for the run (long-poll up to 60s per call)
{ "name": "synthboard.session.get",
  "arguments": { "session_id": "<id>", "wait_ms": 60000 } }
// → { v4_phase: "done", decision_brief, memo: { verdict,
//     confidence_0_100, conditions, dissent } }

What you'll see

• Within seconds: session_id, task_id, and a link to watch live on synthboard.ai.
• Phase progress as the board moves: intake → staffed → research → debate → memo.
• On completion: the decision memo — verdict, confidence, conditions, and the strongest dissent — or a shaped artifact for non-decision asks.

Sessions can't auto-start from a bare question. That protects users and their credit balance from runaway agent loops. You have two paths:

Bare calls (question only, no plan_id and no setup signal) return validation_error with actionable guidance.

Two rooms

Express intake & the decision brief

Sessions started over MCP/API skip the interactive intake: a single facilitator pass turns your question + context into a decision brief — the framed question, the known facts, and the staffed board (which advisors, which seats, why). The brief is returned on session.get as decision_brief.

Board phases

v4_phase tracks the run: intake → staffed → research → debate → memo → done. Each seated advisor researches independently, the board debates with genuinely opposed theses, and the run terminates in a deliverable.

The deliverable: memo or shaped artifact

• Decision boards deliver a decision memo: the verdict, confidence (0–100), the conditions that would flip it, and the strongest dissent — under a named author.
• Every other ask delivers a board artifact shaped to the question — a plan, forecast, comparison, research brief, diagnosis, and more. Read it via board_artifact or the synthboard://session/{id}/memo resource.

Reconvene: Round N+1

A finished board isn't continued — it's reconvened. When something changed, call synthboard.session.reconvene({session_id, whats_changed}). The new round opens from the board's delivered call (verdict, confidence, dissent) plus your update, re-briefs, and runs — returning a new session_id linked to the parent. (session.continue remains for legacy-engine sessions and redirects boards here.)

Consult turns

A Consult is a conversation, billed per turn. Each synthboard.consult.message call sends one message to the seated expert and returns their reply — plus a composed document when the ask calls for one (a memo, an email, a plan). If wait_ms elapses, the turn keeps running server-side; re-read via session.get.

Your World Model & wm_scope

The board keeps a dossier on your world — identity, situation, goals, constraints, the names that matter — and a searchable memory of every delivered call. Agents read it via the synthboard://world-model resource and search it with synthboard.world_model.search (decisions, memos, board artifacts, world-model facts). Every session binds a wm_scope at creation (accepted by session.plan and session.start):

A reconvened round inherits its parent's scope — an off-record board's Round 2 stays off the record. The weekly Board Brief is readable at synthboard://briefs/latest.

Every paid tier gets the full feature surface — no lockouts. Credits self-price richness. Max synths shows the default per tier; the live value is account-configurable and enforced server-side.

Rate limits are per-user (or per-OAuth-client) per bucket. The baseline numbers below apply to Pro; other tiers multiply the baseline — Free ×0.15, Max ×3.3, Ultra ×16 (minimum 1). Buckets without explicit config get a bounded default of 30/min. Concurrent-session caps are enforced atomically — there's no way to race past them.

Hit a limit? The error tells you exactly which cap and when to retry (retry_after_s). Watch live headroom on the usage dashboard.

• One key per client. Separate keys for Claude Desktop, Cursor, and automation scripts — revocation stays surgical.
• Rotate quarterly. Click Rotate on a key to create a replacement with the same scopes. Old key works for 24 hours while you update clients.
• Set a cap for automation. For n8n, Zapier, cron, anywhere you can't watch — a daily credit cap prevents runaway loops.
• Never commit keys. Keep them out of git. If exposed, revoke instantly — it takes effect in real time.
• Scope down. A read-only automation doesn't need session:write. Create keys with just the scopes you need.

Most MCP clients (Claude Desktop, Cursor, Windsurf, Zed, scripts) authenticate with a Bearer API key — simplest, fastest. Browser-based clients like Claude.ai web don't accept raw keys; they use OAuth 2.1 for user-mediated consent. SynthBoard exposes a native, spec-compliant Authorization Server at the standard discovery endpoints.

Discovery metadata

• GET /.well-known/oauth-authorization-server — RFC 8414 AS metadata
• GET /.well-known/oauth-protected-resource — RFC 9728 protected-resource metadata
• GET /.well-known/jwks.json — public JWKS for token verification

Flow

1. Dynamic client registration (RFC 7591): POST /api/oauth/register with your client metadata. https-only redirect URIs required.
2. Authorize: send user to /api/oauth/authorize with response_type=code, code_challenge (S256), resource (your MCP URL), scopes.
3. Consent page: user sees plain-English scope descriptions and approves. CSRF-protected.
4. Token exchange: POST /api/oauth/token with the code + PKCE verifier. Receive a 10-minute access token and 7-day rotating refresh token.
5. Use on /api/mcp — JWT in Authorization: Bearer. Server validates signature, audience (aud must match resource URL, RFC 8707), expiry, and revocation status on every call.
6. Refresh: rotate the refresh token before the access expires. Reused old refreshes trigger grant-chain revocation.

Board runs take 30 seconds to a few minutes. Instead of polling, subscribe and let SynthBoard call you. There are two contracts with different signatures — verify with the right one:

Delivery guarantee

Every started session ends in exactly one terminal event — session.complete, session.failed (including engine timeouts swept by the watchdog, delivered with reason: "timeout"), or session.cancelled. Build state machines on that invariant.

Retries — both systems

Any non-2xx retries with backoff at 1, 5, 15, 60, 240 minutes — 5 attempts total. Subscriptions additionally auto-disable after 10 consecutive failures (re-enable in the Control Center, which resets the breaker).

Verify — subscriptions (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

function verifySubscriptionWebhook(
  rawBody: string, sigHeader: string, tsHeader: string, secret: string,
): boolean {
  if (Math.abs(Date.now() / 1000 - Number(tsHeader)) > 300) return false; // replay guard
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(`${tsHeader}.${rawBody}`).digest("hex");
  const a = Buffer.from(sigHeader), b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Verify — legacy per-key (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyLegacyKeyWebhook(
  rawBody: string, sigHeader: string, secret: string, // whsec_...
): boolean {
  const expected = "sha256=" +
    createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(sigHeader), b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

MCP Resources are the "GET" side of SynthBoard — read them any time for the latest state. Resource subscriptions are not supported: for live board tracking, poll synthboard.session.get with wait_ms (long-polls up to 60s per call), or use webhooks to be called when a run finishes.

All session-scoped resources enforce ownership — cross-tenant reads return not_found, never a leak. Catalog resources are public read-only.

11 slash-prompts

Pre-configured commands — each routes through the plan-first flow with a mode signal./synthboard-consult opens the 1-on-1 room.

A few statuses differ over REST where HTTP semantics demand it (e.g. concurrent_session_limit → 409, upstream_error → 502).