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.

What it can do

39 tools, grouped by what they touch:

• Workspace: workspace_acquire · workspace_status · workspace_release
• Filesystem: fs_stat · fs_list · fs_read · fs_search · fs_apply_patch · fs_write_binary · fs_write_file
• Project intelligence: project_bootstrap · project_instructions · project_skills_list · project_skill_read
• Git: git_status · git_diff
• Exec: exec_run
• Terminal: terminal_list · terminal_status · terminal_create · terminal_write · terminal_key · terminal_read · terminal_snapshot · terminal_interrupt · terminal_close · terminal_reset
• Browser/visual: browser_ensure · browser_set_viewport · browser_reload · browser_open · browser_action · browser_snapshot · visual_capture · visual_get · visual_compare
• Ops: ops_status · ops_cleanup
• Meta: server_info

Two of those are easy to overlook:

• fs_write_file moves 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. See filesystem-binary-write.md.
• visual_capture + visual_compare close the loop on work you cannot see. Screenshot before and after a change and diff the pixels. See frontend-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_env gate plus systemd ReadWritePaths=.
• 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
deploy/http.env.example	Secrets and env → /etc/codeagent-mcp/http.env
deploy/projects.example.yaml	Project registry → /etc/codeagent-mcp/projects.yaml
deploy/codeagent-mcp-http.service	systemd unit (edit ReadWritePaths and UID)
deploy/Caddyfile.example	TLS reverse proxy → loopback :8765

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-mcp

That 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