Skip to main content
Glama

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

  1. Plan: The cloud orchestrator decides what to read or delegate and sets explicit contract limits.

  2. Execute: Tandem sends a bounded task to the local model inside a confined workspace.

  3. Verify: Tandem runs syntax checks, acceptance tests, and lexical quote/number verification.

  4. Review: The orchestrator inspects job_evidence or job_diff and 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 (README.md)

~2,127 tok (90.4%)

3,602

36.2 s · 1/3 quotes (contested)

Targeted grep QA (agent.py)

~27,572 tok (99.5%)

837

22.2 s · 2/2 quotes (quote_only)

Multi-file survey (8 files)

~69,202 tok (99.4%)

107,172

864.0 s · 11/11 quotes (checked)

Git history (30 commits)

~3,554 tok (96.8%)

53,712

420.6 s · completed

Structured extraction (pyproject.toml)

~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 · VERIFIED (0 repairs)

Multi-file bugfix (config_loader.py)

~1,561 tok (92.2%)

8,278

37.1 s · VERIFIED (0 repairs)

Code Generation

Orbital simulation, direct (Gemini 4 Hydrogen)

Orbital simulation, with Tandem (Gemini 4 Hydrogen + qwen3.8-27b@iq3_s)

3D neon portal, direct (Gemini 4 Hydrogen)

3D neon portal, with Tandem (Gemini 4 Hydrogen + qwen3.8-27b@iq3_s)

Workload

Cloud Output Saved (Est.)

Local Tokens

Time / Verified

Orbital animation (1 file)

~1,748 tok (42.7%)*

63,324

984.2 s · VERIFIED (46/46 met)

3D neon portal (4 modules)

~2,491 tok (51.0%)*

237,029

2,464.4 s · VERIFIED (69/69 met)

*Excludes ~5,529 and ~9,708 est. cloud input tokens to inspect receipts and job_evidence.


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.py

Restart your MCP client (Claude Code, Codex, or Antigravity), then run your first check:

Run executor_status

See 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, or GEMINI.md (see Getting Started).


Features Overview

  • Read & Analyze: ask, digest_file, digest_many, extract_from_file

  • Delegate & Execute: delegate, delegate_many, digest_command

  • Inspect & Control: job_status, job_diff, job_evidence, job_feedback, job_rollback, job_continue, job_stop

  • Models & Monitoring: executor_status, executor_probe, ledger_report

  • Project Knowledge: lesson_add, lessons

See the Complete MCP Tool Reference.


Security by Design

  • OS sandbox (bubblewrap): On Linux, TANDEM_SANDBOX defaults to secure (fail-closed if bubblewrap is unavailable). Commands run with allowlisted system dirs, an empty tmpfs over host $HOME, /tmp, and /run, read-only SKIP_DIRS, stripped secret env vars, and network/PID/IPC namespace isolation.

  • Compatibility mode warning: On systems without bubblewrap (macOS, Windows, or TANDEM_SANDBOX=compatible/auto), commands run without OS filesystem isolation, relying on command-text checks (allow_run/DENY), outbound symlink refusal, and workspace stamp() verification.

  • Contracts & file protection: Strict contracts require concrete goals, write_globs, and verify_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=1 enforces full backup coverage; incomplete rollbacks report partial_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 with Gemini 4 Hydrogen + qwen3.8-27b@iq3_s on 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/s probed): digest_file 14.84 s, delegate bugfix 23.78 s (5,124 local tokens, VERIFIED, 0 repairs) vs direct LM Studio completion 8.46 s (305 local tokens, unverified).

  • Historical suite (3.1.0, Nov 2026): Measured with Fable 5.2 + qwen3.8-27b@iq3_s on 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 tools
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.

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

    A3.5/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local, permissioned development workflows from compatible AI clients, including filesystem editing, interactive terminals, durable jobs, Git operations, and semantic browser testing.
      37 npm
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      6
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      An 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.
      128
      1
      ISC