Agent Workstation
Provides Git repository operations as part of the developer workflow, including repository context discovery and version control tasks inherited from Coding Tools MCP.
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., "@Agent Workstation call workspace_guide here, load the relevant rule, then review my staged changes"
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.
Agent Workstation
简体中文 · Security · Architecture · Client setup
Bring an MCP client into your developer workflow. Prefer APIs and CLIs over clicking screens.
A small, opinionated adapter built on Coding Tools MCP. It adds explicit workstation trust, multi-repository context discovery, a lazy rules/skills/recipes entry point, and bounded command previews. It does not implement a new model, agent loop, SQL engine, browser driver, or secret vault.
What is actually new?
Inherited from Coding Tools MCP | Added here |
Files, patches, search, Git, process lifecycle, MCP transport | Explicit |
Output retention, references, pagination | 8 KiB default head/tail preview with stderr budgeting |
Root instruction loading | Bounded multi-repo discovery and target-path rule lookup |
Generic command execution |
|
The adapter pins upstream commit bedb632e1afd2e9ec9b268a50fe0b04695c22c64.
Its package metadata says 0.3.0; this is not a claimed upstream 0.5 release.
Upstream-private imports/hooks are isolated in agent_workstation/compat/coding_tools.py.
A mismatched upstream build fails at startup rather than silently running an untested adapter.
Related MCP server: MCP Lab
Install and try
Requirements: Python 3.11+, Git; macOS or Linux. Your own MCP client supplies the model. No Codex installation or model API key is required by this server. The package is installed from GitHub; it is not published to PyPI in this release.
# An isolated environment; does not alter another MCP installation.
python3 -m venv .venv
. .venv/bin/activate
python -m pip install "git+https://github.com/zix-chen/agent-workstation.git@v0.1.1"
agent-workstation --workspace /path/to/repository --doctor
agent-workstation --workspace /path/to/repository --stdioGeneric stdio MCP configuration (use an absolute executable path):
{
"mcpServers": {
"agent-workstation": {
"command": "/absolute/path/to/.venv/bin/agent-workstation",
"args": ["--workspace", "/absolute/path/to/work", "--mode", "workspace", "--stdio"]
}
}
}Ask the client: “Call workspace_guide for this repository, read the relevant rules/skill, then review this change. Report evidence and what you did not verify.”
Explicit workstation access
agent-workstation --workspace "$HOME/work" --mode trusted-workstation --stdioThis gives commands your real HOME, local developer configuration, network access and access outside the workspace. Commands can read secrets, modify files and operate services with your user privileges. It is NOT secret isolation or protection from prompt injection. Use trusted code and a trusted agent, or a disposable account/VM with reduced credentials.
Default workspace mode retains upstream safe command gates, isolated HOME and structured
path validation. It is not a complete OS sandbox, especially on macOS. Repository rules
are workflow guidance, not permission enforcement. See SECURITY.md.
Rules, skills and recipes
work/
AGENTS.md
repo-a/
AGENTS.md
.agents/skills/review/SKILL.md
repo-b/
src/AGENTS.mdworkspace_guide(path="repo-a") returns applicable rule paths and skill name/description/hash.
It does not inject every skill's full body. The agent selects and fully reads the smallest
relevant skill. Same-name skills retain their source paths. Startup avoids recursive workspace
walks, skips generated/worktree directories and uses Git metadata at actual repository roots.
Target-path lookup can still find rules under a skipped tree when explicitly selected.
Recipes are explicitly loaded TOML, never auto-executed:
agent-workstation --workspace "$PWD/examples/demo-service" --config "$PWD/examples/demo-service/workstation.toml" --stdioSee the runnable example and configuration contract.
External skill roots require explicit config and trusted-workstation mode.
kubectl, mysql, redis-cli, cloud CLIs and their credentials are user-managed, not bundled integrations.
Reproduce the demo and benchmark
git clone https://github.com/zix-chen/agent-workstation.git
cd agent-workstation
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m unittest discover -s tests -v
python scripts/demo.py
python scripts/benchmark_output.py
python scripts/check_release.pyThe demo uses a temporary copy of a fake backend, calls real MCP tools, checks a local HTTP health endpoint, diagnoses a missing demo configuration, and verifies the corrected process. It uses no private infrastructure or model credentials. It is a deterministic integration demo, not a claim of autonomous model task success.
The benchmark reports output bytes and serialized response bytes. It does not measure model
tokens, subscription quotas, speedups, or dollars saved. Explicit output arguments override
defaults. Follow read_output references when previews truncate; retained output can expire
or lose its middle segment. Save an authorized log file for durable/full logs.
HTTP and remote clients
An optional loopback HTTP listener requires a bearer token even on localhost:
# Supply a random 32+ character secret through your process supervisor/secret manager.
# Never put the real value in this repo, the README, or a model prompt.
agent-workstation --workspace /path/to/work --transport http --port 8765
# Reads AGENT_WORKSTATION_HTTP_TOKEN; startup refuses an absent/short token.Remote access requires your own authenticated HTTPS transport and a compatible client. OAuth registration and tunnels are not implemented by this V1. A generic stdio configuration is not a ChatGPT web connection. See client setup and verification boundaries. No public listener or tunnel is installed automatically.
A real run transcript is available in docs/demo-output.txt.
Scope and status
V0.1 is a small developer-tool release, not an enterprise platform. Computer/browser automation, GUI secret filling, company-specific integrations, production deployment automation and a plugin marketplace are intentionally excluded. See validation for actual test results.
Design decisions cover the adapter architecture, trust model, and verification boundaries.
License and attribution
Apache-2.0. Built on Coding Tools MCP, Copyright 2026 Coding Tools MCP Contributors. See NOTICE and THIRD_PARTY_NOTICES.md. No private repository history, employee accounts, business code or production configuration is distributed.
The pinned upstream read_file also caps a page at 2,000 lines. Raising max_bytes does not remove that cap; use next_start_line to read the remaining pages.
Available Tools
19 toolsapply_changesApply changesADestructive
Apply line-addressed file changes atomically. Prefer this over apply_patch when you know the line numbers: nothing has to match. Each change names an action (create, write, edit, delete, move, copy), and a path. write is an upsert: it needs the revision read_file reported when the path exists, but may omit it when creating a missing path. edit, delete, move, and copy always need that revision; create rejects it and asserts absence. edit takes line operations (replace, delete, insert_after, insert_before) whose numbers all refer to the file as read, not to the result of earlier edits in the same call. content is whole lines: "" is zero lines and a trailing newline adds a blank line. One path per call; use apply_patch to chain several edits onto one file. Example: {"changes":[{"action":"edit","path":"app.py","revision":"","edits":[{"op":"replace","start_line":10,"end_line":12,"content":"new line"}]}]}
Inputs: changes (required), dry_run, idempotency_key. Returns: ok, clean, error, dry_run, +8 more
apply_patchApply patchADestructive
Stage, validate, and atomically apply a V4A patch envelope. Each hunk locates itself by its context, so the context must be unique in the file; when it is not, add a scope header (@@ def my_function) naming the enclosing block, or add '*** End of File' to anchor the hunk at the end. A blank context line may be written as "" or as a single space. Matching is graded exact, then ignoring trailing whitespace, then ignoring indentation width, and the grade actually used comes back as match_quality. Success returns each file's revision, total_lines, and changed_ranges. Several updates to one path in one envelope chain in order. Full format reference: docs/tools-and-schemas.md. Example: *** Begin Patch *** Update File: app.py @@ -old +new *** End Patch
Inputs: patch (required), dry_run, idempotency_key. Returns: ok, clean, error, dry_run, +8 more
check_exec_environmentCheck exec environmentARead-onlyIdempotent
Return lightweight exec_command sandbox and environment status known to the server.
Inputs: no named parameters. Returns: ok, error, warnings, workspace, +3 more
exec_commandExecute commandADestructive
Run a bounded command under runtime policy. Pass workdir explicitly for reconnect-safe paths. yield_time_ms is only how long this call waits (default 10s); timeout_ms is the total process lifetime (default 300s). A command still running when the call returns keeps running under its command_id; poll it with write_stdin or read_output. Example: {"cmd":"pytest -q","workdir":".","yield_time_ms":30000}. Retained output is bounded per stream; for very large output redirect to a file (cmd > out.log 2>&1) and page it with read_file or search_text.
Inputs: cmd (required), cwd, env, tty, +7 more. Returns: ok, error, signal, status, +31 more
git_blameGit blameCRead-onlyIdempotent
Return bounded git blame metadata for a workspace file.
Inputs: path (required), rev, end_line, max_lines, +1 more. Returns: ok, path, error, lines, +2 more
git_diffGit diffBRead-onlyIdempotent
Return unified git diff for workspace changes. Untracked files are included as additions by default, so a newly created file is verifiable here.
Inputs: path, paths, staged, unstaged, +3 more. Returns: ok, diff, error, files, +3 more
git_logGit logCRead-onlyIdempotent
Return recent git commits with bounded structured metadata.
Inputs: ref, path, skip, max_count. Returns: ok, error, commits, is_repo, +2 more
git_showGit showCRead-onlyIdempotent
Return bounded git show output for a revision.
Inputs: rev, path, paths, max_bytes, +2 more. Returns: ok, error, files, content, +2 more
git_statusGit statusBRead-onlyIdempotent
Return git working tree status for the workspace.
Inputs: path, max_entries, include_untracked. Returns: ok, error, branch, entries, +3 more
kill_commandKill commandCDestructive
Terminate a server-managed command by command_id. Example: {"command_id":"abc","signal":"KILL"}.
Inputs: command_id (required), signal, wait_ms, verbosity, +3 more. Returns: ok, error, killed, signal, +33 more
list_dirList directoryCRead-onlyIdempotent
List directory entries inside the configured workspace.
Inputs: path, sort, max_depth, recursive, +3 more. Returns: ok, path, error, entries, +5 more
list_filesList filesCRead-onlyIdempotent
List workspace files using glob filters.
Inputs: glob, path, sort, patterns, +4 more. Returns: ok, path, error, files, +5 more
read_fileRead fileBRead-onlyIdempotent
Read a UTF-8 text file slice inside the configured workspace.
Inputs: path (required), encoding, end_line, max_bytes, +2 more. Returns: ok, path, error, content, +15 more
read_outputRead outputARead-onlyIdempotent
Read retained command output using an output_ref returned by exec_command/write_stdin. Each stream retains the earliest output (head) plus the most recent output (rolling tail); bytes between them may be evicted and are reported via evicted_gap_bytes. Example: {"output_ref":"command:abc:stdout","offset":0,"limit":4096}.
Inputs: output_ref (required), limit, offset, stream. Returns: ok, error, limit, offset, +20 more
search_textSearch textCRead-onlyIdempotent
Search UTF-8 workspace files for text or regex matches.
Inputs: query (required), glob, path, regex, +6 more. Returns: ok, error, query, engine, +8 more
server_infoServer infoARead-onlyIdempotent
Return server, workspace, project-context, auth, policy, and fixed-tool metadata.
Inputs: no named parameters. Returns: ok, error, tools, server, +5 more
view_imageView imageCRead-onlyIdempotent
Return a workspace image as MCP image content.
Inputs: path (required), max_bytes, max_width, max_height, +1 more. Returns: ok, path, bytes, error, +5 more
workspace_guideFind target rules, skills and recipesARead-onlyIdempotent
Find applicable repository instructions and skill metadata for a target path. Read the selected full files before acting; no execution or permission grant.
Inputs: path. Returns: ok, error
write_stdinWrite stdinB
Poll or interact with a running command by command_id. Empty chars wait for output; non-empty chars writes to stdin. Example: {"command_id":"abc","chars":"","yield_time_ms":10000}.
Inputs: command_id (required), chars, verbosity, preview_bytes, +2 more. Returns: ok, error, signal, status, +30 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clearly distinct resource+action purposes, such as file reading/listing/searching versus command execution and Git inspection. The main overlap is between apply_patch and apply_changes, which both modify files and could require an agent to read descriptions carefully before choosing one.
Tool names consistently use snake_case and mostly follow predictable prefixes such as read_, list_, search_, apply_, git_, and exec_. Minor deviations exist (server_info and workspace_guide are noun-based rather than verb_noun), but the naming remains readable and coherent.
The 19 tools fit a broad workspace-agent scope covering file operations, patching, command execution, process management, Git inspection, image viewing, and guidance. It is slightly on the heavy side relative to a typical 3-15 tool server, but each cluster addresses a real capability.
The surface covers core workspace lifecycle operations: read/list/search, create/write/edit/delete via apply_changes, patching via apply_patch, command execution and management, and key Git read operations. Minor gaps such as dedicated Git commit/stage tools or simple directory metadata operations can be handled through exec_command, so the set is largely complete for its purpose.
Maintenance
Related MCP Connectors
Governed AI agent skills — one library, distributed to devs and exposed to remote agents over MCP.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to execute commands, edit files, run Git workflows, and perform validated independent reviews in real development environments through Docker-based runtimes with separated developer and auditor permissions.MIT
- AlicenseNot gradedqualityBmaintenanceEnables developers to build, test, debug, and operate MCP servers from VS Code or CI, while also exposing trusted MCP capabilities to AI agents.MIT
- AlicenseDqualityCmaintenanceEnables controlled local developer operations including file and process management, shell execution, SSH, WSL, Docker, Git, browser and desktop automation, media processing, and asynchronous jobs through MCP.146MIT
- AlicenseNot gradedqualityAmaintenanceEnables teams to onboard remote MCP servers, enforce function-level permissions and credential modes, and let developers expose permitted tools through a unified MCP endpoint with search and execute functions while auditing usage.MIT