Coding MCP

Production-ready MCP server that lets AI agents perform coding tasks on remote repositories.

What is it?

coding-mcp is an MCP (Model Context Protocol) server that exposes your code repositories as a set of tools and resources that AI agents can use to read, write, search, and run commands — all without the agent needing local access to the repositories.

Primary goal: deploy one server on a machine that hosts your code, then connect any MCP-compatible agent (Claude, Cursor, etc.) to it. The agent can browse files, edit code, run builds and tests, manage git, and more — all through structured MCP tool calls.

┌─────────────────────────────────────────────┐
│  AI Agent (Claude / Cursor / any MCP client) │
└────────────────┬────────────────────────────┘
                 │  MCP over HTTP or STDIO
                 ▼
┌─────────────────────────────────────────────┐
│           coding-mcp server                  │
│  (runs on the machine with your repos)       │
│                                              │
│  Tools: files · git · search · commands      │
│  Resources: project index · file content     │
│  Prompts: implement · review · fix tests     │
└──────────────────┬──────────────────────────┘
                   │  filesystem + git
                   ▼
        /projects/repo-a  /projects/repo-b  …

Documentation

• Quickstart: https://coding-mcp.omaicode.com
• API Reference: https://coding-mcp.omaicode.com/api-reference
• Source Code Analysis: https://coding-mcp.omaicode.com/architecture/source-code-analysis
• CLI and Registry Guide: https://coding-mcp.omaicode.com/guides/cli-and-registry

Highlights

• Multi-project registry with persistent indexing
• Safe file operations and patching (structured edits + unified diff hunks)
• Git command suite with structured output
• Allowlist-based command runner with timeout and output limits
• Binary-safe file resources (text and base64 blob modes)
• Dual transport support: STDIO and HTTP (streamable or SSE)
• HTTP API-key authentication + RBAC (viewer/editor/admin)
• OpenTelemetry hooks for request and tool-level tracing
• Structured operation envelopes with request IDs and timing
• Audit logging for mutating actions

Quick Start

Install globally:

npm install -g @kieutrongthien/coding-mcp

Register one or more project roots (the directories that contain your repos):

coding-mcp init /projects

Start the server:

# HTTP transport (for remote agents)
coding-mcp serve --transport http --host 0.0.0.0 --port 4000 --mode streamable

# STDIO transport (for local agents like Cursor or Claude Desktop)
coding-mcp serve --transport stdio

Build from source

git clone https://github.com/kieutrongthien/coding-mcp.git
cd coding-mcp
cp .env.example .env
npm install
npm run build
npm install -g .

CLI Commands

Development shortcuts (no build step needed):

npm run dev:stdio
npm run dev:http
npm run dev:serve -- --transport http --host 127.0.0.1 --port 3001 --mode sse

MCP Tools

Tools are the primary interface for agents. Each tool accepts a project_id (returned by list_projects) and operates within that project's root, preventing any path traversal outside it.

Project Tools

File Tools

Search Tools

Git Tools

Command Tools

Commands run inside the project directory. Only commands on the ALLOWED_COMMANDS allowlist are permitted.

MCP Resources

Resources expose read-only data that agents can fetch directly by URI.

MCP Prompts

Prompts provide pre-built instructions that agents can invoke to start structured coding workflows.

MCP Client Examples

Claude Desktop (STDIO)

{
  "mcpServers": {
    "coding-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/coding-mcp/dist/src/main/stdio.js"],
      "env": {
        "PROJECTS_ROOTS": "/projects"
      }
    }
  }
}

Cursor (STDIO)

{
  "mcpServers": {
    "coding-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/coding-mcp/dist/src/main/stdio.js"],
      "env": {
        "PROJECTS_ROOTS": "/projects,/srv/repos",
        "ENABLE_STDIO": "true",
        "ENABLE_HTTP": "false"
      }
    }
  }
}

Generic HTTP MCP client

{
  "mcpServers": {
    "coding-mcp-http": {
      "url": "http://your-host:4000",
      "headers": {
        "x-api-key": "editor-key"
      }
    }
  }
}

Configuration

Use environment variables directly or provide a JSON/YAML config file via MCP_CONFIG_PATH.

Core settings

Security settings

Observability settings

HTTP Security (Auth/RBAC)

Enable API-key authentication when exposing the HTTP transport to external agents.

ENABLE_AUTH=true
AUTH_HEADER_NAME=x-api-key
AUTH_API_KEYS=viewer-key:viewer:viewer1,editor-key:editor:editor1,admin-key:admin:admin1

Pass the key in the request header:

x-api-key: editor-key

Roles:

HTTP Monitoring Endpoints

When HTTP transport is enabled:

OpenTelemetry

Tracing can be exported over OTLP HTTP:

ENABLE_OTEL=true
OTEL_SERVICE_NAME=coding-mcp
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20token

Emitted spans:

• mcp.http.request
• mcp.tool.{operation}

Response Contract

All tool responses follow the same envelope format.

Successful operation:

{
  "ok": true,
  "project_id": "abc123",
  "operation": "read_file",
  "data": {},
  "warnings": [],
  "errors": [],
  "request_id": "uuid",
  "duration_ms": 12
}

Failed operation:

{
  "ok": false,
  "operation": "write_file",
  "error_code": "SECURITY_ERROR",
  "message": "Operation blocked for protected path",
  "details": {},
  "request_id": "uuid",
  "duration_ms": 7
}

Architecture

The server uses one shared core with modular layers:

• config: environment/config-file loading and runtime validation
• core: response contracts, errors, logging, telemetry hooks, locks
• services: filesystem, git, patching, command execution, auth, project registry
• mcp: tool/resource/prompt registries bound to shared services
• main: CLI and transport bootstrap (stdio, http, serve/init/add/remove)

STDIO and HTTP transports share the same service layer, keeping behavior consistent while allowing transport-specific controls (such as HTTP authentication).

Validation

npm run typecheck
npm test

License

MIT