CodeMCP Documentation

01 / GETTING STARTED

Overview

CodeMCP is a lightweight, local Model Context Protocol (MCP) server designed specifically for developer workspaces. Rather than uploading your entire source code to a cloud service or relying on opaque embeddings, CodeMCP turns your current directory into an intelligent, sandboxed environment that your assistant can explore on demand.

When an AI client (such as Claude Desktop, Cursor, or Cline) is paired with CodeMCP, it interacts through a standardized set of tools: searching symbols, inspecting project trees, reading source files, performing surgical edits, and running tests or build commands.

02 / GETTING STARTED

Quickstart

Launch CodeMCP directly inside any Git repository or project folder using your preferred package runner. No global install is required.

cd path/to/your-project
npx codemcp

Upon starting, CodeMCP outputs connection details:

┌─────────────────────────────────────────────────────────────┐
│  CodeMCP Server v1.1.4                                     │
│  Project Root : C:\Users\azure\Documents\projects\CodeMCP   │
│  Transport    : stdio / SSE (http://localhost:4173/mcp)     │
│  Permissions  : approval (Ask before write/execute)         │
│  Context File : CONTEXT.md (loaded)                         │
└─────────────────────────────────────────────────────────────┘
[mcp] Ready for AI client connections...

03 / GETTING STARTED

Architecture & Protocol Flow

CodeMCP implements the open standard MCP specification using two interchangeable transports: stdio for local desktop agents and Server-Sent Events (SSE) over HTTP for remote or web-based clients.

04 / CLIENT SETUP

Client Setup & Integrations

Connect your favorite AI assistant to CodeMCP. Most modern IDEs and clients support the Model Context Protocol natively.

05 / CLIENT SETUP

Claude Desktop Setup

Add CodeMCP to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codemcp": {
      "command": "npx",
      "args": ["-y", "codemcp", "--project", "/absolute/path/to/project"]
    }
  }
}

06 / CLIENT SETUP

Cursor IDE Setup

Open Cursor Settings → Features → MCP → Add New MCP Server:

• Name: codemcp
• Type: command
• Command: npx -y codemcp

Or configure via project .cursor/mcp.json:

{
  "mcpServers": {
    "codemcp": {
      "command": "npx",
      "args": ["-y", "codemcp"]
    }
  }
}

07 / CLIENT SETUP

VS Code & Cline Setup

In VS Code with the Cline or Continue extension installed, edit the MCP settings file:

{
  "mcpServers": {
    "codemcp": {
      "command": "npx",
      "args": ["-y", "codemcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

08 / CLIENT SETUP

Windsurf Cascade Setup

In Windsurf, open Cascade settings → External Tools (MCP):

{
  "mcpServers": {
    "codemcp": {
      "command": "npx",
      "args": ["-y", "codemcp"]
    }
  }
}

09 / TOOLS REFERENCE

Tools Reference Overview

CodeMCP exposes 6 standard tools designed for granular, safe interactions. All filesystem actions are strictly confined within the configured projectPath.

10 / TOOLS REFERENCE

list_files

Inspects directory contents within the project tree. Automatically respects .gitignore and protected path configurations.

11 / TOOLS REFERENCE

read_file

Reads textual content from an allowed file. Rejects paths that resolve outside the project root or match protectedPaths.

12 / TOOLS REFERENCE

search_code

High-speed ripgrep-powered code search over the project. Enables your assistant to find symbol definitions, references, or strings in milliseconds.

13 / TOOLS REFERENCE

write_file

Creates a new file or replaces existing contents. In approval mode, CodeMCP displays a diff prompt to the developer before committing changes.

14 / TOOLS REFERENCE

edit_file

Performs surgical find-and-replace edits on targeted code blocks. Minimizes hallucinations and preserves surrounding context.

15 / TOOLS REFERENCE

execute_command

Executes a shell command inside the project directory. Requires explicit enabling via codemcp.json or the --allow-exec CLI flag.

16 / CONFIGURATION

codemcp.json Specification

Optional configuration file placed in the project root to define boundaries, permissions, and protected files.

{
  "$schema": "https://codemcp.dev/schema.json",
  "projectPath": ".",
  "permissionMode": "approval",
  "protectedPaths": [
    ".env*",
    "**/*.pem",
    "**/*.key",
    "secrets/**"
  ],
  "allowedCommands": [
    "pnpm test",
    "npm run lint",
    "git status",
    "git diff"
  ],
  "tunnel": {
    "enabled": false,
    "provider": "cloudflare"
  }
}

17 / CONFIGURATION

CONTEXT.md Guide

A CONTEXT.md file in your project root acts as the AI assistant's onboarding brief. CodeMCP automatically injects this context when the client initializes, preventing repeated prompting and aligning code generation with your architectural style.

# Project Context & Engineering Standards

## Technology Stack
- Next.js 15 (App Router), React 19, TypeScript
- Styling: Tailwind CSS v4 + Lucide Icons

## Architecture Rules
1. All client components must be marked with "use client" at top.
2. Use server actions for data mutations; never expose internal API tokens.
3. Every new component should include accessible ARIA labels.

## Testing & Verification
- Run `pnpm test` before submitting any proposed diff.
- Keep dependencies lean; avoid adding ad-hoc npm packages.

18 / CONFIGURATION

Permission Modes

CodeMCP supports three distinct operational modes to match your confidence and workflow:

19 / CLI REFERENCE

CLI Flags & Options

Customize runtime behavior when launching codemcp:

20 / CLI REFERENCE

Connecting Remote Web Clients

Want to use a cloud assistant (such as Claude.ai or ChatGPT) with your local project? Launch CodeMCP with the --tunnel flag:

npx codemcp --tunnel

[tunnel] Establishing secure HTTPS bridge...
[tunnel] Public URL: https://codemcp-tunnel-74x9.trycloudflare.com/mcp
[tunnel] Auth token: cdmcp_sec_9941a87b320...
[mcp] Ready for remote client connections.

The tunnel connects via end-to-end TLS directly to your machine. No code is stored on intermediary proxies.

21 / TROUBLESHOOTING

FAQ & Troubleshooting