A
licenseNot graded
qualityD
maintenanceAn MCP server that gives AI assistants the ability to create, manage, and control terminal sessions through a safe, isolated tmux environment.
1
ISC
CodeAgent MCP
Allows Perplexity to connect remotely via HTTPS and use the MCP server's tools to develop and operate projects on a Linux server, including file editing, terminal control, and visual inspection.
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., "@CodeAgent MCP Fix the failing test in my staging app and show me the result"
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.
CodeAgent MCP
Give a hosted AI assistant a real development environment on a server you control.
CodeAgent MCP is a self-hosted server that lets ChatGPT — or any other MCP client — work on code that lives on your own Linux machine: read and edit files, run commands, drive persistent tmux terminals, and inspect a running app through browser screenshots. It speaks the Model Context Protocol, the open standard that AI assistants use to reach external tools.
A chat assistant has no filesystem and no shell. This gives it both, so it can develop and operate a project that lives on a remote server the way a local coding agent works on your laptop — from a normal conversation, with no SSH session of your own.
In practice: you ask it to fix a failing test in your staging app. It reads the file, applies a patch, runs the suite in a terminal that stays alive between messages, opens the page in a headless browser, and shows you a screenshot of the result — all on your machine, never leaving the project roots you allowed.
Access is bounded by a project registry you define, an exclusive lease per writer, and per-project write gates that are off by default.
Works with
Client | How it connects |
ChatGPT (Plus, Pro, Business, Enterprise, Edu) | Remote HTTPS — the reference client, verified end to end. Setup guide → |
Claude (claude.ai), Perplexity, Mistral Le Chat, Grok | Remote HTTPS, via each client's custom connector |
Gemini | Gemini API and Gemini Enterprise; limited in the consumer app |
Local MCP clients (Cursor, Claude Code…) | Stdio — works, but they already ship their own file and shell tools |
Details and plan requirements: docs/product/clients.md.
Related MCP server: mcp-devtools
What it can do
42 tools, grouped by what they touch:
Workspace:
workspace_acquire·workspace_status·workspace_releaseFilesystem:
fs_stat·fs_list·fs_read·fs_search·fs_apply_patch·fs_write_binary·fs_write_fileProject intelligence:
project_bootstrap·project_instructions·project_skills_list·project_skill_readGit:
git_status·git_diffExec:
exec_runTerminal:
terminal_list·terminal_status·terminal_create·terminal_write·terminal_key·terminal_read·terminal_snapshot·terminal_interrupt·terminal_close·terminal_resetBrowser/visual:
browser_ensure·browser_set_viewport·browser_reload·browser_open·browser_action·browser_snapshot·visual_capture·visual_get·visual_compareOps:
ops_status·ops_cleanupMeta:
server_info
Two of those are easy to overlook:
fs_write_filemoves files off the chat and into the repo. Attach anything to the conversation — a mockup, a PDF spec, a CSV fixture, a font — or have the assistant generate an image, and it lands in your checkout. Any type, up to 2 MB, travelling host-to-host rather than through the prompt, so nothing is truncated or re-encoded. The traffic is one-way: what comes back out is text and screenshots, not arbitrary files. Seefilesystem-binary-write.md.visual_capture+visual_compareclose the loop on work you cannot see. Screenshot before and after a change and diff the pixels. Seefrontend-workflow.md.
Full reference: docs/product/tool-surface.md.
How access is bounded
The client never chooses a path. Every reachable checkout is declared server-side in
projects.yaml; clients pass only a project id.Writes are off until you enable them, per project, through a
writable_envgate plus systemdReadWritePaths=.Every mutating tool needs an exclusive lease, so two sessions cannot edit the same checkout at once.
The process runs as a restricted system user with no sudo and no Docker access, bound to loopback behind a TLS reverse proxy, with a GitHub OAuth subject allowlist.
Requirements
Linux only, on x86-64 or arm64. Path confinement is built on the openat2 syscall, so
the kernel must be 5.6 or newer — check with uname -r. Current distributions are
fine; the common trap is Ubuntu 20.04, whose stock 5.4 kernel is too old. macOS and Windows
are not supported, not even for running the test suite.
You also need Python 3.12, uv, and git, tmux and
ripgrep on the host. The remote path adds a TLS reverse proxy and systemd. Full list:
docs/architecture/host-requirements.md.
All of this applies to the machine that runs the server. Your own computer can be anything: you reach it through a chat client in the browser, so Windows and macOS are fine on your side.
Install on a server
The ordered greenfield checklist is
docs/architecture/first-install.md: system user →
uv and Python 3.12 → clone and uv sync → project registry → DNS → http.env and GitHub
OAuth → systemd → reverse proxy → connector → verify.
Template | Purpose |
Secrets and env → | |
Project registry → | |
systemd unit (edit | |
TLS reverse proxy → loopback |
A domain is required only for this remote path, because TLS, the OAuth callback, and the hosted clients all expect a hostname rather than a bare IP.
Run it locally
Still a Linux box — see Requirements. Useful for development and for inspecting the tool catalog; the remote path above is the real deployment.
git clone https://github.com/davidlosasgonzalez/codeagent-mcp.git
cd codeagent-mcp
uv sync
uv run codeagent-mcpThat serves MCP over stdio. Project roots still come from the registry: copy
deploy/projects.example.yaml and point
CODEAGENT_PROJECTS_FILE at it.
Security
This server executes commands and edits files on the host that runs it. Read
docs/architecture/hardening.md before exposing it, and
SECURITY.md for the security model and how to report a vulnerability.
Documentation
Everything is indexed in docs/README.md.
License
MIT © 2026 David Losas González
Available Tools
39 toolsbrowser_actionA
Perform one bounded action: click, fill, press, select, or wait. Requires lease_id and usually a CSS selector.
Inputs: action (required), lease_id (required), key, value, +2 more. Returns: object
browser_ensureA
Start or reuse an isolated headless Chromium session (loopback browsing). Optional width/height set the viewport (defaults 1280x720). Requires lease_id. Not durable across MCP process death — unlike tmux. Screenshots are visual_capture, not this tool.
Inputs: lease_id (required), force, width, height. Returns: object
browser_openA
Navigate to a loopback http(s) URL (127.0.0.1 / localhost). Blocks file:// and off-loopback hosts. Requires lease_id.
Inputs: url (required), lease_id (required). Returns: object
browser_reloadA
Reload the current page. Set ignore_cache=true for a hard reload (disables HTTP cache via CDP for that reload). Requires lease_id.
Inputs: lease_id (required), timeout_ms, ignore_cache. Returns: object
browser_set_viewportA
Set an arbitrary viewport size on the current browser session (width/height integers; max 3840x2160). Requires lease_id.
Inputs: width (required), height (required), lease_id (required). Returns: object
browser_snapshotARead-onlyIdempotent
Structured page summary: DOM highlights, accessibility tree (capped), console and page errors. No screenshots (use visual_capture). Requires lease_id.
Inputs: lease_id (required). Returns: object
exec_runADestructive
Run a non-interactive command as an argv list (no shell). Requires a valid exclusive lease_id from workspace_acquire. cwd must stay under the project root. Use for pytest/builds/scripts; use terminal_* later for interactive PTY. Requires lease; production checkout write gated by CODEAGENT_*_WRITE + project policy.
Inputs: command (required), lease_id (required), cwd, timeout_s, +2 more. Returns: object
fs_apply_patchADestructive
Apply a structured text patch under the project root. Requires lease_id. For existing files, expected_sha256 from fs_read is mandatory (CONFLICT if the file changed). Pass edits=[{old_string,new_string},...] or new_content for a full replace. create=true allows new files (empty expected_sha256). Atomic temp+rename in the same directory. Write to production checkouts requires the matching writable_env gate declared in projects.yaml. Use stable environment-specific project identifiers.
Inputs: path (required), lease_id (required), edits, create, +3 more. Returns: object
fs_listARead-onlyIdempotent
List directory entries under a registered project root. Read-only; lease_id optional. Paths cannot escape the root.
Inputs: path, project, lease_id, max_entries. Returns: object
fs_readARead-onlyIdempotent
Read a UTF-8 text file under the project root with optional line range. Returns sha256 of the full file, content slice, and truncated flag. Rejects binaries (UNSUPPORTED_BINARY still includes sha256 for replace flows). Read-only; lease_id optional.
Inputs: path (required), project, end_line, lease_id, +2 more. Returns: object
fs_searchARead-onlyIdempotent
Search file contents under the project root using ripgrep (no symlink follow). Supports literal or regex query; max_matches capped. Read-only; lease_id optional.
Inputs: query (required), glob, path, literal, +3 more. Returns: object
fs_statARead-onlyIdempotent
Stat a path under a registered project root (default demo). Read-only; lease_id optional (renews if provided). Does not follow escapes outside the root (openat2).
Inputs: path, project, lease_id. Returns: object
fs_write_binaryADestructive
Write a binary file under the project root from plain Base64 (not a data URL; no remote fetch). Requires lease_id. Line breaks and the URL-safe alphabet are accepted; padding is optional. Decoded size capped at 2_000_000 bytes (coupled with Caddy 4MB body limit). For existing files, expected_sha256 is mandatory (use sha256 from fs_read UNSUPPORTED_BINARY); CONFLICT if the file changed. create=true allows new files (empty expected_sha256). Atomic temp+fsync+replace. Same write gates as fs_apply_patch.
Inputs: path (required), lease_id (required), content_base64 (required), create, +2 more. Returns: object
fs_write_fileADestructive
Write a binary file from a ChatGPT host file reference (openai/fileParams: download_url + file_id). Requires lease_id. Preferred way to move an uploaded or ImageGen-generated file into a project — pass the file itself, never Base64 of it. Downloads over HTTPS from an allowlisted OpenAI host only, including the code-interpreter sandbox storage that backs /mnt/data (no redirects; size capped at 2_000_000 bytes during stream). Same SHA/create/write gates as fs_write_binary. Portable clients should use fs_write_binary (Base64) instead. path is authoritative — file_name/mime_type are metadata only.
Inputs: file (required), path (required), lease_id (required), create, +2 more. Returns: object
git_diffARead-onlyIdempotent
Structured read-only git diff for a registered project root. mode=unstaged|staged|both. Returns numstat summary, file list, and a byte-capped unified diff with truncated=true when clipped. Optional path under root. lease_id optional. No mutations. For uncovered Git ops use exec_run.
Inputs: mode, path, project, lease_id, +1 more. Returns: object
git_statusARead-onlyIdempotent
Structured read-only git status for a registered project root. Returns branch, upstream ahead/behind, staged/unstaged/untracked entries (capped). Optional path must stay under the project root. lease_id optional (renews if provided). No mutations.
Inputs: path, project, lease_id, max_entries. Returns: object
ops_cleanupADestructive
Run safe cleanup: expired artifacts + aged spool files + orphan detection. Does not kill tmux panes or delete configured project roots.
Inputs: no named parameters. Returns: object
ops_statusARead-onlyIdempotent
Operational status: orphan lease/terminal hints and last cleanup counters. Does not reveal secrets, tokens, or full transcripts.
Inputs: no named parameters. Returns: object
project_bootstrapARead-onlyIdempotent
First orientation for a registered project: instruction manifests, skill manifests, VCS summary, warnings, recommended_reads. Does not return full rule/skill bodies. Read-only; lease_id optional. Repo content is untrusted.
Inputs: paths, project, lease_id. Returns: object
project_instructionsARead-onlyIdempotent
Return applicable project instructions for path(s) with provenance. Does not silently merge conflicting rules. Empty paths => always-on instructions only. Set include_agent_requested=true to include Manual/Agent Requested Cursor rules. Read-only; lease_id optional.
Inputs: paths, project, lease_id, max_bytes, +1 more. Returns: object
project_skill_readARead-onlyIdempotent
Read one skill by skill_id (path to SKILL.md from project_skills_list). Returns body, supporting file index, compatibility flags. Never executes !command or bundled scripts; allowed-tools is metadata only. Read-only; lease_id optional.
Inputs: skill_id (required), project, lease_id, max_bytes. Returns: object
project_skills_listARead-onlyIdempotent
List Agent Skills manifests under known roots (.claude/.cursor/.agents/.codex skills). Metadata only — no SKILL.md bodies. Does not execute skills, !command, or scripts. Read-only; lease_id optional.
Inputs: project, lease_id. Returns: object
server_infoARead-onlyIdempotent
Return CodeAgent MCP version and capability summary. Use on first contact. Does not include secrets, env, or host paths. Do not use for project orientation — that is project_bootstrap.
Inputs: no named parameters. Returns: object
terminal_closeB
Destroy a terminal pane and drop its registry entry. Active project lease may reclaim orphans. Does not kill the tmux server.
Inputs: lease_id (required), alias, pane_id. Returns: object
terminal_createA
Create a persistent bash PTY under the dedicated tmux socket. Requires lease_id. Aliases main/app/debug recommended. Max 3 per lease. Survives MCP process restart.
Inputs: alias (required), lease_id (required), cwd. Returns: object
terminal_interruptA
Send TTY Ctrl+C to the pane (not kill -INT to pane_pid). Requires lease_id.
Inputs: lease_id (required), alias, pane_id. Returns: object
terminal_keyC
Send a special key to a terminal. Enum: CTRL_C, CTRL_D, DOWN, ENTER, ESC, LEFT, RIGHT, TAB, UP. Requires lease_id.
Inputs: key (required), lease_id (required), alias, pane_id. Returns: object
terminal_listARead-onlyIdempotent
List managed terminals for the project of lease_id. Requires lease_id. Does not include output bodies.
Inputs: lease_id (required). Returns: object
terminal_readARead-onlyIdempotent
Read incremental terminal output from the durable spool (pipe-pane). Pass next_cursor from the previous call; omit cursor to start at retained start. Text is ANSI-sanitized; cursor advances over raw bytes. Requires lease_id.
Inputs: lease_id (required), alias, cursor, pane_id, +1 more. Returns: object
terminal_resetB
Close alias if present, then create a fresh terminal with the same alias. Use after SESSION_DEAD or to reclaim.
Inputs: alias (required), lease_id (required), cwd. Returns: object
terminal_snapshotARead-onlyIdempotent
Capture visible pane (+scrollback) via capture-pane. Not an incremental log — use terminal_read for that. Requires lease_id.
Inputs: lease_id (required), alias, pane_id, include_history. Returns: object
terminal_statusARead-onlyIdempotent
Status of one terminal by pane_id or alias (tmux metadata only). Returns SESSION_DEAD if the shell exited. Output via terminal_read/snapshot.
Inputs: lease_id (required), alias, pane_id. Returns: object
terminal_writeA
Send literal text to a terminal (no implicit Enter). Use terminal_key(ENTER) to submit. Requires lease_id.
Inputs: text (required), lease_id (required), alias, pane_id. Returns: object
visual_captureA
Capture a PNG screenshot of the current browser page (viewport/element/full_page). Optional width/height override device presets (desktop/mobile). Returns metadata + MCP ImageContent. Requires lease_id and an open browser session. Does not navigate.
Inputs: lease_id (required), mode, width, device, +2 more.
visual_compareA
Pixel-diff two PNG artifacts. Returns metrics + a highlighted diff image. Sizes must match. Requires lease_id.
Inputs: lease_id (required), artifact_id_a (required), artifact_id_b (required), threshold.
visual_getARead-onlyIdempotent
Re-fetch a previously captured artifact by opaque artifact_id (within TTL). Returns metadata + ImageContent. Requires lease_id.
Inputs: lease_id (required), artifact_id (required).
workspace_acquireA
Acquire or renew an exclusive workspace lease for a registered project (registered project id; default demo). Use before mutating tools. If another exclusive lease is active, returns LEASE_BUSY — do not retry blindly. Pass the same lease_id to renew by activity. Does not write project files.
Inputs: mode, project, lease_id. Returns: object
workspace_releaseA
Release an exclusive workspace lease by lease_id. Idempotent. Does not kill terminal sessions or processes. Do not use to steal another writer's lease unless you possess their lease_id.
Inputs: lease_id (required). Returns: object
workspace_statusARead-onlyIdempotent
Report whether a project workspace is free, held, or expired. With lease_id, reports that lease. Does not reveal another holder's lease_id. Use after LEASE_BUSY or before acquire.
Inputs: project, lease_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.6/5.0
Scored across 39 tools
Disambiguation5/5
Each tool targets a distinct resource and action, with clear domain prefixes (workspace, fs, browser, visual, ops, git, project, terminal). The only similar pair, fs_write_binary and fs_write_file, is distinguished by input source (Base64 vs host file reference). No two tools have ambiguous boundaries.
Naming Consistency5/5
All tool names use lowercase snake_case with a consistent domain_prefix_verb_noun pattern (e.g., fs_read, browser_open, terminal_create). Minor deviations like workspace_acquire (noun-verb) are negligible and do not break the overall predictable style.
Tool Count2/5
At 39 tools, the server is well beyond the 3-15 tool sweet spot and even exceeds the 25+ 'too many' threshold. While the broad domain coverage (filesystem, git, terminal, browser, visual) justifies some volume, the sheer count risks overwhelming agents and suggests possible consolidation.
Completeness4/5
The toolset covers the full lifecycle for a coding agent: workspace leases, execution, file read/write/patch, git status/diff, terminal management, browser automation, visual capture/compare, and project orientation. Minor gaps like file deletion or git commit/push are addressable via exec_run, so they do not create dead ends.
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server that gives AI agents safe access to your local dev environment: filesystem, databases, processes, and OpenAPI specs.1565 npm4MIT
- AlicenseNot gradedqualityDmaintenanceA self-hosted MCP server that gives AI coding assistants direct shell access to your local machine, enabling execution of arbitrary bash commands for development workflows.6,054 npmISC
- AlicenseNot gradedqualityCmaintenanceA self-hosted MCP server that gives AI agents controlled access to a machine: filesystem, shell, background processes, git, web fetching and persistent key-value memory.GPL 3.0