Tandem MCP
Tandem MCP lets a cloud AI delegate bounded reading, extraction, command analysis, and coding work to a local OpenAI-compatible LLM, then verify and control the results.
Check and probe the local executor’s status, models, capabilities, context, and speed.
Run text tasks with the local model, including schema-constrained output and multi-sample agreement.
Digest single files, many files, or command outputs into verified summaries with quote checks.
Extract structured JSON from files and flag values not found in the source.
Delegate bounded code-edit jobs or multi-task batches with contracts, write limits, verify commands, dependencies, and parallel workers.
Inspect job status, diffs, and cited evidence; continue, stop, accept, give feedback, or roll back jobs.
Enforce sandbox/security controls, protect files, and snapshot changes for rollback.
Track usage, token savings, model performance, and job outcomes via the ledger.
Add and manage project-specific lessons for the executor.
Serves as the local executor backend: any Ollama-served model can be the executor, with its context length auto-detected and its capabilities probed (native tool calls, server-forced JSON schema, printed reasoning). Delegated tasks use that model to read, edit and run files in a workspace under a contract with server-run acceptance checks, journalled diffs and rollback.
Uses the OpenAI-compatible chat completions API to reach the executor model (LM Studio, Ollama, llama.cpp, vLLM, Jan, KoboldCpp, LocalAI), including schema-forced JSON replies for models without native tool calling and stripping of reasoning text from answers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Tandem MCP delegate: fix the failing tests in src/utils, run the checks, and show me the diff"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Tandem MCP is an MCP server that pairs a cloud AI orchestrator (Claude Code, Codex, Gemini) with a local OpenAI-compatible LLM (LM Studio, Ollama, llama.cpp, vLLM). The cloud model keeps architectural decisions and final review; the local model reads large files and executes bounded edits while Tandem enforces contracts, runs checks, verifies quotes, and enables rollback.
Architecture: How Tandem Works
Plan: The cloud orchestrator decides what to read or delegate and sets explicit contract limits.
Execute: Tandem sends a bounded task to the local model inside a confined workspace.
Verify: Tandem runs syntax checks, acceptance tests, and lexical quote/number verification.
Review: The orchestrator inspects
job_evidenceorjob_diffand accepts (job_feedback) or restores (job_rollback).
The local model does not receive unrestricted control over the machine. Actual isolation strength depends on configuration and platform (Bubblewrap on Linux vs command-text checks in compatibility mode).
Learn more -> Architecture (English PDF · Italian PDF)
Related MCP server: ForgeBridge
Why Tandem MCP?
Save cloud context: The local model reads large files, logs, and docs, returning only verified answers and quotes.
Controlled delegation: Tasks are bounded by contracts, writable globs, command allow lists, and read-only test guards.
Deterministic verification: Baseline checks, syntax validation, lexical quote checks, and acceptance tests verify results without trusting the local model's word.
Local model flexibility: Works with LM Studio, Ollama, llama.cpp, vLLM, and other OpenAI-compatible endpoints, with role-based model routing.
Review and rollback: Inspect diffs and cited lines before accepting, and restore recoverable changes without overwriting later user edits.
Usage insights: Track calls, local tokens, retry counts, and estimated cloud input savings in
ledger_report.
Benchmarks: Tandem MCP v3.6.1
Gemini 4 Hydrogen + Qwen 27B (LM Studio)
Reproduced on v3.6.1 (010cbb6), qwen3.8-27b@iq3_s (65536 ctx, 23.6 tok/s), bubblewrap sandbox, cache disabled, 1 cloud tok = 3.6 chars (Estimated).
Reading & Extraction
Workload | Cloud Saved (Est.) | Local Tokens | Time / Verified |
Full-file QA ( | ~2,127 tok (90.4%) | 3,602 | 36.2 s · 1/3 quotes ( |
Targeted grep QA ( | ~27,572 tok (99.5%) | 837 | 22.2 s · 2/2 quotes ( |
Multi-file survey ( | ~69,202 tok (99.4%) | 107,172 | 864.0 s · 11/11 quotes ( |
Git history ( | ~3,554 tok (96.8%) | 53,712 | 420.6 s · completed |
Structured extraction ( | ~187 tok (85.6%) | 633 | 11.9 s · schema valid (0 loose) |
Delegated Fixes
Workload | Cloud Saved (Est.) | Local Tokens | Time / Verified |
Micro bugfix (6 lines) | ~171 tok (58.7%) | 6,498 | 27.7 s · |
Multi-file bugfix ( | ~1,561 tok (92.2%) | 8,278 | 37.1 s · |
Code Generation
Orbital simulation, direct ( | Orbital simulation, with Tandem ( |
3D neon portal, direct ( | 3D neon portal, with Tandem ( |
Workload | Cloud Output Saved (Est.) | Local Tokens | Time / Verified |
Orbital animation (1 file) | ~1,748 tok (42.7%)* | 63,324 | 984.2 s · |
3D neon portal (4 modules) | ~2,491 tok (51.0%)* | 237,029 | 2,464.4 s · |
*Excludes ~5,529 and ~9,708 est. cloud input tokens to inspect receipts and job_evidence.
View Orbital Animation Comparison · View 3D Portal Comparison
Reports & raw data: Gemini v3.6.1 Report · Raw JSON · Generation JSON · Reproducible Script
Historical Benchmark (Tandem 3.1.0 / Fable 5.2): Fable Report · Orbital Demo · 3D Portal Demo
Quick Start
Prerequisites: Python 3.11+, a local OpenAI-compatible server (e.g. LM Studio), and bubblewrap on Linux for OS-level sandboxing.
1. Install
git clone https://github.com/ALENOC/tandem-mcp
cd tandem-mcp
python3 -m venv .venv
.venv/bin/pip install .2. Start a local LLM server (LM Studio example)
Open LM Studio, load a model, and start the local server on its default OpenAI-compatible endpoint:
http://127.0.0.1:1234/v1(The endpoint can differ depending on your LM Studio or Ollama/vLLM configuration; Tandem auto-detects common local ports or reads TANDEM_BASE_URL.)
3. Register with your MCP client
.venv/bin/python scripts/install.pyRestart your MCP client (Claude Code, Codex, or Antigravity), then run your first check:
Run executor_statusSee Getting Started for manual stdio JSON configs, installer flags, and multi-client setup.
Typical Prompts
Analyze large logs (digest_file)
Use tandem-mcp to inspect server.log and list every error with line numbers.Understand a codebase (digest_many)
Ask tandem-mcp what each Python module in src/ is responsible for.Fix a bug safely (delegate -> job_diff -> job_feedback / job_rollback)
Delegate fixing the failing test in tests/test_auth.py to tandem-mcp, then show me job_diff.Check token usage (ledger_report)
Show me ledger_report for the last 7 days.Want your AI agent to use Tandem automatically? Add standing rules to
CLAUDE.md,AGENTS.md, orGEMINI.md(see Getting Started).
Features Overview
Read & Analyze:
ask,digest_file,digest_many,extract_from_fileDelegate & Execute:
delegate,delegate_many,digest_commandInspect & Control:
job_status,job_diff,job_evidence,job_feedback,job_rollback,job_continue,job_stopModels & Monitoring:
executor_status,executor_probe,ledger_reportProject Knowledge:
lesson_add,lessons
See the Complete MCP Tool Reference.
Security by Design
OS sandbox (
bubblewrap): On Linux,TANDEM_SANDBOXdefaults tosecure(fail-closed ifbubblewrapis unavailable). Commands run with allowlisted system dirs, an empty tmpfs over host$HOME,/tmp, and/run, read-onlySKIP_DIRS, stripped secret env vars, and network/PID/IPC namespace isolation.Compatibility mode warning: On systems without
bubblewrap(macOS, Windows, orTANDEM_SANDBOX=compatible/auto), commands run without OS filesystem isolation, relying on command-text checks (allow_run/DENY), outbound symlink refusal, and workspacestamp()verification.Contracts & file protection: Strict contracts require concrete goals,
write_globs, andverify_commands. Protected test files are restored automatically if modified.Snapshots, rollback & redaction: Edits are journaled and pre-run files are snapshotted up to configurable caps (
TANDEM_REQUIRE_FULL_BACKUP=1enforces full backup coverage; incomplete rollbacks reportpartial_rollback). Tool outputs redact detected secrets by default.
See Security Model for full details and SECURITY.md to report vulnerabilities.
Performance & Benchmarks
Tandem trades local execution time for reduced cloud context on reading and test-driven fixes. Generating brand-new code from a contract preserves quality when design is written into constraints, but adds contract-authoring and review overhead so total cloud savings are smaller or negative compared to one cloud turn.
Latest full suite (
3.6.1, Nov 2026): Measured withGemini 4 Hydrogen+qwen3.8-27b@iq3_son i9-9900K / RX 6800 XT (58.7%-99.5% estimated cloud input savings on reading/bugfixes; 46/46 and 69/69 constraints on full demo generation).Live validation (
3.5.1, Nov 2026): Measured on LM Studio (qwen3.8-27b@iq3_s,10.7 tok/sprobed):digest_file14.84 s,delegatebugfix23.78 s(5,124local tokens,VERIFIED,0repairs) vs direct LM Studio completion8.46 s(305local tokens, unverified).Historical suite (
3.1.0, Nov 2026): Measured withFable 5.2+qwen3.8-27b@iq3_son i9-9900K / RX 6800 XT (58.7%-99.3% estimated cloud input savings on reading/bugfixes; 19-31 min on full demo generation).
See Benchmarks for full tables, hardware specs, and methodology.
Comparison With Alternatives
Rather than merely connecting a cloud agent to a local LLM, Tandem introduces bounded delegation, deterministic checks, lexical evidence tracking, and controlled review with journaled rollback.
See the full comparison (compiled Nov 2026 from public READMEs).
Documentation
License & Attribution
MIT License · Copyright (c) 2026 Alessandro Nocentini (@ALENOC) · Security Policy
Available Tools
19 toolsaskB
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.
Inputs: prompt (required), model, samples, max_tokens, +2 more. Returns: result
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.
Inputs: goal (required), workspace (required), model, context, +13 more. Returns: result
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.
Inputs: tasks (required), workspace (required), model, context, +9 more. Returns: result
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 question (default: did it succeed,
and what are the errors) with checked quotes, the last lines of the output, and the path
of the full output in case you need to read a part yourself. The command runs as you wrote
it, with your rights: the limits apply only to commands the executor chooses.
Inputs: cwd (required), command (required), timeout, question, +1 more. Returns: result
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.
Inputs: path (required), question (required), grep, model, +1 more. Returns: result
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".
Inputs: glob (required), root (required), question (required), max_files, +1 more. Returns: result
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 delegate through JSON replies. Runs by itself at the first
use of a model; force repeats it (after a change of server settings or of chat template).
Inputs: force, model. Returns: result
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.
Inputs: no named parameters. Returns: result
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.
Inputs: path (required), json_schema (required), instructions (required), grep. Returns: result
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.
Inputs: hint (required), job_id (required), extra_steps, wait_seconds. Returns: result
job_diffB
Unified diff of what a delegated job changed (one file if path is given).
Inputs: job_id (required), path, max_lines. Returns: result
job_evidenceA
The lines the executor cited for each contract constraint, with context lines around them,
read from the files as they are now. This is the focused inspection of a delegated job: a few
dozen lines instead of the whole diff. It satisfies the inspection asked by job_feedback when
the job is verified by checks that failed before the work and every constraint has checked
evidence; in any other case it says so and job_diff is still needed. Lines that no constraint
cites are covered only by the verify commands: use job_diff when you want to read them.
Inputs: job_id (required), context. Returns: result
job_feedbackA
Your verdict on a delegated job. It feeds the acceptance statistics, and lesson (one
sentence on what to do differently, or what was right) is given to the executor at its
next tasks in the same project. For non-trivial changes, weak checks, or jobs with contract
constraints, and for any job that had no check, accepted=True requires inspecting job_diff(job_id) first (and setting
constraints_verified=True when constraints were provided).
Inputs: job_id (required), accepted (required), lesson, constraints_verified. Returns: result
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.
Inputs: job_id (required). Returns: result
job_statusB
Receipt of a delegated job or batch, waiting up to wait_seconds if it is still running.
Inputs: job_id (required), wait_seconds. Returns: result
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.
Inputs: job_id (required), wait_seconds. Returns: result
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.
Inputs: days. Returns: result
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.
Inputs: text (required), project_path (required). Returns: result
lessonsC
Lessons the executor has for a project. remove_containing deletes those with that text.
Inputs: project_path (required), remove_containing. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Autonomous cloud agent tasks: real browser + your tools, structured evidence-backed results.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables Claude Code to hand off mechanical work — file edits, code lookups, and lint triage — to a local Ollama model that reads and edits files directly, so file contents never enter Claude's context. Returns only a compact receipt, and reports success only after the change passes a deterministic syntax/project gate, rolling back and escalating on failure.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables local, permissioned development workflows from compatible AI clients, including filesystem editing, interactive terminals, durable jobs, Git operations, and semantic browser testing.37 npm1Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI agents to delegate complex coding tasks, refactorings, and automated code reviews to OpenAI Codex and Google Antigravity CLIs, running them autonomously in YOLO mode with process supervision.6MIT
- AlicenseCqualityCmaintenanceAn MCP execution layer that lets capable AI models safely control a developer workstation for file edits, terminal and process execution, Git operations, language-server analysis, browser and Windows UI automation, media processing, job/resource control, and checkpointing. It also coordinates durable single- or multi-agent tasks across providers with leases, dependency graphs, evidence logs, repair loops, and separate verification gates.1281ISC