Tandem MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TANDEM_HOME | No | Ledger, lessons, model capabilities, cache and job folders. Default: `~/.local/share/tandem-mcp`. | |
| TANDEM_MODEL | No | Model to use. Default: the loaded chat model, else the first one. | |
| TANDEM_API_KEY | No | Key for a server that asks for one. Default: `local`. | |
| TANDEM_CONTEXT | No | Context length in tokens, when the server does not report it. Default: reported value, else 8192 (Ollama: 4096). | |
| TANDEM_SANDBOX | No | `auto`, `require` or `off`. Default: `auto`. | |
| TANDEM_TIMEOUT | No | Seconds allowed for one completion. Default: 900. | |
| TANDEM_BASE_URL | No | Address of the OpenAI compatible server (`LM_STUDIO_BASE_URL` is read too). Default: found by itself. | |
| TANDEM_SANDBOX_NET | No | `1` lets sandboxed commands use the network. Default: off. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Hybrid orchestration (cloud model = architect & reviewer, local model = reader & bounded executor, free to use):
Reading & extraction: use digest_file (with grep when possible), digest_command, digest_many, and extract_from_file instead of reading large files/logs into cloud context. Quotes and numbers are checked against the source; if a result is flagged unsupported/contested or ask(samples>1) shows agreement < 1.0, inspect only the cited lines.
Bounded coding: delegate under a strict contract. Every task must name the files it may write (write_globs), give verify_commands that fail until the work is done and that run the code (tests, build, a script), and list as constraints every value, name and behaviour the result must have, one requirement per constraint (the executor must cite a line for each, so a compound constraint hides requirements). A contract without them is refused. The quality of the result is set by the contract: state interfaces, exact numbers and formulas, not wishes. Design stays with you: write every design decision into the contract before the work (structure, layout, colors, sizes, motion, edge cases). The executor takes the simplest reading of what is left unsaid, and after the work you can only check the result against what the contract says, not against a solution you do not have. For multi-file or >150-line features, split into small modular tasks via delegate_many (with
afterdependencies) rather than asking a small local model for one giant single-shot file.Keep frontier quality: verify_commands prove code runs/parses, not design or visual polish. Inspect every job: job_evidence shows the lines the executor cited for each constraint (a few dozen lines, enough when the checks failed before the work and every constraint has evidence), job_diff the whole change. Render the output for UI work; use job_continue(hint=...) for targeted fixes, job_rollback to undo cleanly, and job_feedback / lesson_add so mistakes become standing project rules.
Skip delegation for trivial 1-line edits or purely open-ended design with no check. The executor is slow. If a call runs past the client timeout and moves to the background, do not cancel it or redo its work with the cloud model on your own: ask the user whether to keep waiting or to stop it with job_stop.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| executor_statusA | State of the local executor: server, models, which one is in use, its context length, what it can do (when it has been probed) and how its commands are confined. |
| executor_probeA | Measure what a local model can do on this server: native tool calls, JSON schema forced
by the server, reasoning text, speed. The result is stored and the tools adapt to it: a model
without tool calling still does |
| askB | A text task for the local executor (drafting, translation, boilerplate, classification). json_schema: optional JSON schema (as a string) that the answer must follow. samples: 2 to 5 runs the task several times and reports how many runs agree. Agreement below 1.0 on a factual or structured task means the executor is unsure: check or do it yourself. |
| digest_fileA | Ask a question about a file (text, source, log, JSON, PDF) instead of reading it. The executor reads the whole file, in parts sized to its context, and answers in at most max_words with line references and quotes. The server checks every quote against the file and lists the numbers of the answer that are not in the file. grep: optional regular expression; only matching lines (with context) are read, which is faster on large files when you know what to look for. |
| digest_commandA | Run a command of yours (build, tests, linter, DRC) and get the verdict instead of the output. Returns the exit code, the answer of the executor to |
| digest_manyA | Ask the same question of many files (for example every *.md under a folder). Returns one short answer per file with a checked quote. Use it for surveys such as "which of these documents still mention the old part" or "what does each module export". |
| extract_from_fileA | Structured data from a file, in the JSON schema you give (as a string). Example: a pin table from a datasheet, the failing tests from a log, the parts of a BOM. Values the file does not give come back as null. grep narrows a large file first. Every extracted string and number is looked up in the file: those that are not there are listed after the data, so an invented value is visible. |
| delegateA | Give the local executor a bounded task in a project and get a receipt. The contract is strict (TANDEM_STRICT=0 relaxes it): a call is refused unless it gives a goal with concrete targets, write_globs that name files, and verify_commands that can fail. When the checks only look for text or files (grep, test, ls), or the task writes files whose look no command proves (HTML, CSS, SVG, UI components), constraints are required too. For every constraint the executor must cite, at finish, the line that satisfies it: the server looks the quote up in the file, sends the work back when a constraint has none, and lists the cited lines in the receipt. Constraints are atomic: one requirement each, at most 160 characters, so that every requirement gets its own cited line. When every check already passes before the work and no constraint is given, the job stops before the executor starts, because nothing would prove the work. Accepting a job needs its job_evidence (the cited lines) or its job_diff read. goal: what to do, precise and self-contained (files, names, exact values, expected behaviour). workspace: absolute path of the project folder; the executor cannot leave it. verify_commands: shell commands that must exit 0 for the work to be accepted (tests, build, a grep that must find or not find something). They run after the executor finishes in an isolated sandbox with secret env vars stripped; their failures go back to it for up to max_repairs attempts. Give at least one whenever you can. The files they name (and test folders) are read only for the executor unless write_globs names them. write_globs: files it may write, as globs relative to the workspace. Required; a glob that matches every file ('', '**/') is refused. allow_run: regular expressions of commands the executor itself may run (empty: none). Every part of a pipeline or chain must match one. A pattern matches anywhere in the part: start it with ^ (for example '^pytest\b') so that it names the command and not one of its arguments. immutable: files or globs relative to the workspace that are always read only. read_globs: optional files or globs relative to the workspace the executor may read via read_file, list_files, and search (empty: all workspace files). Note: if allow_run is also set, shell commands run against the mounted workspace and are not filesystem-filtered by read_globs; omit allow_run when strict read confinement is required. context: facts it needs and cannot find in the files. constraints: explicit, checkable contract requirements (coordinates, selectors, invariants) injected into the executor prompt and listed in the receipt for post-run inspection. wait_seconds: how long this call waits; a longer task keeps running, poll it with job_status. baseline: run the checks once before the work. The executor starts from their failures, and the receipt says when a check already passed, which means it proves nothing about this work. max_seconds: time limit of the job (0: none). checks_network: allow network access inside the sandbox when running verify_commands. unjailed_checks: run verify_commands outside bubblewrap (for checks needing host resources). Every file the executor changes is journalled (and command changes are snapshotted): job_diff shows the change, job_rollback undoes it without overwriting later user edits. The syntax of every changed file is checked before the checks run. Good tasks: mechanical edits across files, a function plus its test, docs brought in line with a change, renames. Poor tasks: design choices, anything without a check. |
| delegate_manyB | Give the executor several tasks with an order, each one a contract of its own. tasks: a list of objects with name short unique name goal what to do, self-contained, with concrete targets verify_commands checks of this task that can fail (list of shell commands, required) write_globs files this task may write (list of globs, required) constraints explicit checkable requirements (required when the checks only look for text) after names of the tasks that must succeed first (list) context facts for this task (optional) immutable read-only files or globs for this task (optional) workers: tasks run side by side, for a server with several request slots (default 1). A task starts when the tasks it comes after are verified. A task whose prerequisite failed is cancelled with the reason and not started. Two tasks that run at the same time cannot write the same file: the first to write it owns it until it ends. Each task has its own job, receipt, diff and rollback; job_rollback of the batch undoes all of them, newest first. |
| job_statusB | Receipt of a delegated job or batch, waiting up to wait_seconds if it is still running. |
| job_continueA | Send a stopped job on with a hint of yours, in the same conversation of the executor. For a job that ended blocked, stuck, checks_failed, out_of_steps or out_of_time, or a finished one that needs a correction. The executor keeps what it read and tried, so one sentence from you (the cause it missed, the file to look at, the approach to take) costs far less than a new task. The journal goes on: job_rollback still undoes the whole job. It also works after a restart of the server, since the conversation is saved at every step. |
| job_diffB | Unified diff of what a delegated job changed (one file if path is given). |
| job_stopA | Ask a running job or batch to stop at its next safe point. An in-flight model call is not interrupted: it can take up to TANDEM_TIMEOUT seconds. Returns the receipt, which may still show running. |
| job_evidenceA | The lines the executor cited for each contract constraint, with |
| job_rollbackA | Undo a delegated job: every file it changed goes back to its content before the job. For a batch, every task is undone, newest first. |
| job_feedbackA | Your verdict on a delegated job. It feeds the acceptance statistics, and |
| lesson_addA | Teach the executor a standing rule for a project (or for every project with project_path '*'). Example: 'Comments in English, no em dashes.' The executor reads its lessons before each task. |
| lessonsC | Lessons the executor has for a project. remove_containing deletes those with that text. |
| ledger_reportA | What the local executor did and what it saved: calls and executor tokens per tool, the characters it read against the characters returned to you (with a token estimate), and per model the speed, the share of quotes that failed the check, the outcome of delegated jobs and your verdicts. Use it to decide what is worth delegating, and to which model. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 19 tools
The core delegation lifecycle (delegate, delegate_many, job_status/continue/stop/diff/rollback/evidence/feedback) is cleanly separated by verb, and executor_status vs executor_probe are distinguishable. The main blur is in the read/digest cluster: ask, digest_file, digest_many and extract_from_file all route content to the executor, so an agent must parse descriptions to know whether it wants a prose answer, a per-file survey, or schema-bound structured data. lessons vs lesson_add vs job_feedback's lesson parameter also sit close together but stay workable.
Everything is snake_case and grouped by prefix (job_*, digest_*, executor_*), which makes scanning predictable. Minor deviations: bare 'delegate', 'ask' and 'lessons' break the verb_noun pattern, and lesson_add/lessons are an asymmetric create/list pair. Nothing rises to a real inconsistency problem.
19 tools is on the heavy side, but the surface is broad (delegation, job lifecycle, file digests, lessons, executor introspection, ledger) and nearly every tool maps to a distinct operation rather than a convenience wrapper. The weight comes from describing a contract protocol rather than from redundancy, though trimming the digest cluster would be defensible.
The delegation lifecycle is unusually complete: dispatch, batch, poll, continue, stop, diff, rollback, evidence, verdict, plus persistent lessons and usage reporting. The noticeable gap is enumeration: job_status and the job_* tools all require a job_id, but there is no job_list/jobs tool to discover ids after a server restart or in a later session, forcing the agent to remember them.