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:
| Command | Serves | Source |
|---|---|---|
syndb mcp api | The 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 figures | Manuscript figure inspection | crates/tools/mcp |
syndb mcp check | Build verification and upgrade-report tools | crates/tools/check |
syndb mcp ops | Read-only production operations tools | crates/tools/cli/src/mcp/ops.rs |
syndb mcp review | Assessor-only machine review: queue, evidence, validate, submit proposals | crates/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:
- resolves the checkout from its own path, so the build does not depend on the client’s working directory;
- rejects a missing or unsupported mode with a usage message on stderr and exit status 2;
- runs
nix build git+file://<checkout>#syndb-cli-tools, so only tracked files are imported (notarget/or.direnv/) and build output goes to stderr; and - execs
<store-path>/bin/syndb mcp <mode>.
Prerequisites:
-
nixwith flakes enabled on the client’sPATH(it does not have to be the dev shell). -
A checkout whose
flake.lockresolves. The launcher never runsnix flake update. -
A build of
.#syndb-cli-toolsthat 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-toolsSubsequent 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) | Meaning | Default |
|---|---|---|
SYNDB_REVIEW_SERVER_URL (--server) | API origin for every tool | unset: every tool returns server_not_selected |
SYNDB_REVIEW_SESSION_FILE (--review-session-file) | 0600 assessor session capability file, read per call | unset: 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=1 | also 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