MCP RepoBridge
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCP RepoBridge
A guarded MCP bridge for repository context, Docker-sandboxed commands, document Skills, trusted local MCP servers, and optional Codex handoff.
MCP RepoBridge lets ChatGPT and other MCP clients inspect a project workspace without giving them a host shell.
It exposes a small set of read-only repository tools, routes command execution through a fixed Docker sandbox backed by a filtered disposable workspace, and can optionally hand implementation work off to a local Codex worker. It is intentionally smaller than a general agent framework: it is the bridge between an LLM interface and a repository, not a replacement for your development environment.
Project status (November 2026) — expected final release. ChatGPT and Codex usage quotas are set to be merged in December 2026. Once they share a single pool, the main reason this bridge exists — letting ChatGPT inspect a repo while Codex quota stays separate — goes away, so the project's practical value under ChatGPT will be limited. The repository stays available as-is; no further updates are planned.
Why This Exists
This project came from a pragmatic workflow:
ChatGPT's web UI is good for interactive reading, questioning, and planning.
Codex is better suited for longer implementation work.
Their usage limits and working modes are separate enough that it is useful to let ChatGPT inspect a repository without spending Codex work on every small question.
Exposing a normal local shell to a remote LLM is too much trust.
MCP RepoBridge sits in the middle. ChatGPT can read and search the project via MCP, run bounded checks inside Docker, and, when explicitly enabled, queue tasks for Codex to handle separately.
ChatGPT / MCP client
|
| HTTPS + bearer token
v
MCP RepoBridge
|
|-- read-only host workspace file tools
|
|-- filtered disposable copy -> Docker sandbox execution
|
|-- optional document Skills / trusted host MCP gateway
|
|-- optional Codex task queueThe result is a small, auditable MCP server for people who want the convenience of "connect MCP and start working" without handing an LLM direct access to the host machine.
Related MCP server: engineering-mcp
What It Provides
Default MCP tools:
read_file
read_files
list_directory
grep_files
find_files
project_task_list
project_task_run
exec_container
sandbox_status
sandbox_start
sandbox_stop
sandbox_task_status
sandbox_task_tail
sandbox_task_cancel
workspace_bootstrap
workspace_info
audit_log_tailOptional Codex handoff tools:
codex_task_create
codex_task_list
codex_task_status
codex_task_tail
codex_task_cancelOptional extension tools:
extension_discover
skill_read
mcp_call # only when trusted host MCP execution is enabledWhat it deliberately does not provide:
run_shell
host_exec
write_file
edit_file
arbitrary_dockerSecurity Model
MCP RepoBridge assumes the MCP client and the model may make unsafe requests. The runtime enforces boundaries in code rather than relying on prompts.
Key defaults:
host shell execution is not exposed
host write/edit tools are not exposed
file access is restricted to a configured workspace root
path traversal and symlink escapes are rejected
secret-like paths such as
.env,.ssh,.aws,.gcloud, and.secure-mcpare blocked by defaultcommand execution goes through
docker execinto a fixed containerthe final container receives a filtered, disposable workspace copy instead of the host workspace; secret-like paths are omitted and writes are discarded
the model cannot choose Docker flags, container name, image, or mounts
the default sandbox has
--network nonethe default sandbox does not mount host HOME, SSH keys, cloud credentials, or the Docker socket
command policy rejects common network, Docker, privilege escalation, and destructive commands
HTTP transport enforces Origin and Host allowlists
HTTP MCP sessions have a configured cap and idle TTL
Codex worker child processes receive an allowlisted, secret-filtered environment
extension support and host MCP execution are separate, disabled-by-default gates
Skills are treated as untrusted Markdown instructions and are never executed
host MCP commands, arguments, working directory, environment mappings, and tool allowlists come only from trusted local configuration
an MCP call must use a short-lived discovery ID and matching schema revision
host MCP child-process concurrency is capped and wildcard tool access is rejected
every tool call is audited
every tool result uses a stable status/data/error/next-action envelope
Docker is risk reduction, not perfect isolation. Read SECURITY.md and docs/06-threat-model.md before exposing the runtime through a public tunnel.
Quick Start
Install and build:
npm install
npm test
npm run buildBuild the default sandbox image:
docker build -f docker/Dockerfile.sandbox -t secure-mcp-sandbox:latest dockerStart the bridge for a project:
npm run --silent bridge -- start \
--project-root /absolute/path/to/project \
--tunnel noneStop it:
npm run --silent bridge -- stop \
--project-root /absolute/path/to/projectThe bridge writes generated state under:
<project-root>/.secure-mcp/That directory contains runtime config, bearer tokens, logs, audit records, and optional Codex task state. It is ignored by git and blocked by the file tools.
ChatGPT Setup
For ChatGPT or another remote MCP client, start the HTTP runtime with a tunnel.
Cloudflare Quick Tunnel:
npm run --silent bridge -- start \
--project-root /absolute/path/to/project \
--tunnel cloudflareManaged tunnel or reverse proxy:
npm run --silent bridge -- start \
--project-root /absolute/path/to/project \
--tunnel external \
--public-base-url https://mcp.example.comThe command prints:
publicMcpUrl
tokenIn ChatGPT, configure:
URL: publicMcpUrl
Authentication: Access token / API key
Header scheme: Bearer
Token: token value onlyDo not put Bearer into the token field if the UI already has a Bearer/header
scheme option. The HTTP header must end up as:
Authorization: Bearer <token>For a Linux server deployment flow, see docs/11-linux-server-tunnel.md.
Docker Sandbox
The default sandbox image is intentionally small. It is based on Node and includes:
node
npm
bash
git
ripgrep
ca-certificates
util-linuxIt does not try to be a full polyglot development image. If a project needs Python, Go, Rust, or another toolchain, build a trusted image and select it from local configuration:
{
"sandbox": {
"image": "secure-mcp-sandbox:latest"
}
}The MCP client must not be allowed to choose image names, Docker flags, mount paths, network mode, or container names.
Commands that finish within the configured yield window return inline. Longer
commands become durable sandbox_task_* jobs with incremental log reads and
cooperative cancellation. project_task_list discovers conventional project
tasks without exposing package-script bodies, and project_task_run resolves
the selected task server-side before applying the normal command policy.
Optional Skills and Local MCP Servers
The extension gateway is disabled by default. It adds a low-round-trip flow similar to local MCP/Skill aggregators while preserving two separate trust levels:
document Skills scan configured directories and return bounded
SKILL.mdcontent; no Skill script or runtime is executedlocal MCP servers start an exact stdio command from trusted configuration on the host, discover its allowlisted tools, then proxy a revision-bound call
Copy examples/extensions.example.json, edit the absolute paths and allowlists, then start with:
npm run --silent bridge -- start \
--project-root /absolute/path/to/project \
--tunnel none \
--extensions-config /absolute/path/to/extensions.jsonThe example enables document Skills but keeps hostMcpEnabled false. Change it
to true only after reviewing every configured executable, argument, tool
allowlist, and environment mapping.
The client workflow is:
extension_discover(kind=skill) -> extension_discover(name=...) -> skill_read(revision=...)
extension_discover(kind=mcp) -> extension_discover(name=...) -> mcp_call(discoveryId, revision, tool, arguments)The model cannot pass a process command, arguments, cwd, or environment through any MCP tool. Environment values are copied only by locally configured variable name mappings, and audit records store argument names rather than values. Upstream tool metadata and results are explicitly labeled as untrusted content.
Important: an enabled local MCP server is trusted native host code. It runs with the OS privileges of RepoBridge and is outside the Docker sandbox. Tool allowlists and environment filtering reduce exposure to the model; they do not sandbox a malicious MCP executable.
Optional Codex Handoff
Codex handoff is disabled by default.
When enabled, ChatGPT can queue structured tasks through MCP. A separate local or server-side worker claims the tasks and runs Codex in the workspace.
Start the bridge with handoff tools:
npm run --silent bridge -- start \
--project-root /absolute/path/to/project \
--tunnel none \
--codex-handoff trueRun the worker in another terminal:
npm run --silent codex-worker -- \
--config /absolute/path/to/project/.secure-mcp/runtime.config.jsonDefault worker command:
codex exec --sandbox workspace-write --ask-for-approval never --json -Use this only when you explicitly want Codex to modify the workspace. The MCP request itself only creates or inspects task records. The worker child process does not inherit the full host environment; only configured safe keys/prefixes are passed through, and secret-like variable names are stripped.
Task creation supports idempotency keys and captures the relevant-file/Git baseline. The worker publishes a heartbeat, refuses stale relevant-file context by default, supports running-task cancellation, and records changed files, pre-existing changes, and a diff summary in the final result.
Configuration
Start from:
examples/config.example.json
examples/extensions.example.jsonImportant defaults:
HTTP server binds to
127.0.0.1sandbox network is
nonethe host workspace is not mounted into the final sandbox; a filtered, disposable copy is writable so builds can create temporary outputs
root filesystem is read-only
Linux capabilities are dropped
no-new-privilegesis enabledmemory, CPU, PID, timeout, and output limits are configured
audit logging is enabled
For a low-round-trip client flow, call workspace_bootstrap first. File list
and search tools return opaque cursors, read_files applies aggregate budgets,
and every result includes a structured nextAction when continuation or setup
is needed.
Development
npm install
npm run lint
npm test
npm run buildOptional Docker e2e:
npm run test:e2eThis requires Docker and runs only the gated Docker sandbox e2e suite. Normal
npm test keeps that suite skipped.
Useful docs:
Status
MCP RepoBridge is an early 0.1.x project. The core runtime, HTTP transport,
Docker sandbox lifecycle, document Skill/trusted host MCP gateway, bridge
adapter, and optional Codex handoff flow are in place.
The project is useful today, but interfaces and deployment guidance may evolve as it is tested against more real repositories and MCP clients.
License
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables any MCP client to read, search, patch, and execute commands in a codebase, including interactive sessions and git operations, with permission modes and safety boundaries.18Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables repository-aware lifecycle management and controlled delegation of coding tasks to trusted worker harnesses via MCP, with execution isolation, recovery, and verified handoff.36 npm8Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables autonomous software-engineering tasks in a repository by coordinating filesystem, GitHub, database, and CI/CD tools through MCP, with a deterministic safety boundary for permissions, validation, timeouts, duplicate protection, and test verification.MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to run deterministic AST safety audits, secret scanning, and sandboxed test execution on codebases, with human approval required before any remediation action.5MIT