Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MCP Servers

SynDB ships five Model Context Protocol servers over stdio. All five are compiled into the syndb binary and are selected by a subcommand, so there is one executable to build and one contract to remember:

CommandServesSource
syndb mcp apiThe five read-only public-API tools (api_corpus_status, api_datasets, api_dataset, api_search, api_capabilities)crates/tools/cli-core/src/mcp_api.rs
syndb mcp figuresManuscript figure inspectioncrates/tools/mcp
syndb mcp checkBuild verification and upgrade-report toolscrates/tools/check
syndb mcp opsRead-only production operations toolscrates/tools/cli/src/mcp/ops.rs
syndb mcp reviewAssessor-only machine review: queue, evidence, validate, submit proposalscrates/tools/cli/src/mcp/review.rs

syndb mcp api serves the public API alone and needs no Cargo feature, so the consumer and provider profiles carry it; it is the same five tools syndb mcp ops also exposes.

The standalone binaries syndb-mcp and syndb-check are compatibility binaries around the libraries. They take no mode argument: syndb-mcp always serves figures and syndb-check always serves check. They cannot serve api, ops or review. New client configuration should use syndb mcp <mode>.

The Home Manager module installs one profile binary and publishes the servers that binary can serve as programs.syndb.mcp.servers, each {command, args, env} with command the package’s bin/syndb and args = ["mcp" "<mode>"]. Consumer serves syndb-api; provider adds syndb-review; developer serves all five. A harness module reads that attrset; see Home Manager Module.

syndb mcp api and syndb mcp ops also accept the global --server-url <URL> / SYNDB_SERVER_URL setting; each MCP server forwards it to its API tools.

Repository launcher

The repository .mcp.json starts every server through scripts/syndb-mcp.sh:

{
  "mcpServers": {
    "syndb-figures": {
      "command": "bash",
      "args": ["scripts/syndb-mcp.sh", "figures"],
      "cwd": "."
    },
    "syndb-check": {
      "command": "bash",
      "args": ["scripts/syndb-mcp.sh", "check"],
      "cwd": "."
    },
    "syndb-ops": {
      "command": "bash",
      "args": ["scripts/syndb-mcp.sh", "ops"],
      "cwd": "."
    },
    "syndb-review": {
      "command": "bash",
      "args": ["scripts/syndb-mcp.sh", "review"],
      "cwd": "."
    }
  }
}

The launcher works outside the dev shell (no syndb-mcp on PATH required). It:

  1. resolves the checkout from its own path, so the build does not depend on the client’s working directory;
  2. rejects a missing or unsupported mode with a usage message on stderr and exit status 2;
  3. runs nix build git+file://<checkout>#syndb-cli-tools, so only tracked files are imported (no target/ or .direnv/) and build output goes to stderr; and
  4. execs <store-path>/bin/syndb mcp <mode>.

Prerequisites:

  • nix with flakes enabled on the client’s PATH (it does not have to be the dev shell).

  • A checkout whose flake.lock resolves. The launcher never runs nix flake update.

  • A build of .#syndb-cli-tools that succeeds. On a cold cache the first launch can take longer than an MCP client’s startup timeout; from the repo root, prewarm it once:

    nix build --no-link --print-out-paths git+file://"$PWD"#syndb-cli-tools
    

    Subsequent launches reuse the realized store path.

The launcher never serves a stale binary. If evaluation or the build fails it prints the nix error plus a syndb-mcp: ... failed; no MCP server started line to stderr and exits nonzero; there is no fallback to a previously built store path. stdout is reserved for JSON-RPC.

To serve uncommitted work, git add the files first: a git+file flake copies tracked working-tree files and skips untracked ones.

Review server

syndb mcp review lets an LLM harness work the machine-review queue as an assessor. It reads the queue, serves packet evidence as citable rows, validates a draft assessment and submits it as a machine receipt. A receipt is a proposal, never approval: there is no tool that approves, decides, signs, adopts, attests, prepares, publishes, withdraws, regrants or acquires. Humans make those decisions in the CLI or UI.

Tools: review_queue, review_packet, review_evidence, review_validate, review_submit.

It ignores the global --server-url and has no default server. Configure it in the MCP client’s environment for the server entry:

Variable (flag)MeaningDefault
SYNDB_REVIEW_SERVER_URL (--server)API origin for every toolunset: every tool returns server_not_selected
SYNDB_REVIEW_SESSION_FILE (--review-session-file)0600 assessor session capability file, read per callunset: your syndb auth login session
SYNDB_REVIEW_STATE_DIR (--state-dir)private directory for cached packets, drafts and receipts~/.config/syndb/review-mcp
SYNDB_REVIEW_ALLOW_RESTRICTED=1also serve published packets not marked public_information (only for an approved model provider)off

Publisher sessions and BR-01 targets are refused. Packet contents are untrusted data: they appear only inside quote fields, and the server never follows links found in evidence. See .skills/syndb-review/SKILL.md for the operator workflow.

Manual use

Inside a checkout, the same command works directly:

bash scripts/syndb-mcp.sh figures

In a dev shell, syndb-mcp <mode> is a shim for the launcher:

nix develop -c syndb-mcp check