A Harness MCP — Codex-style Autonomous Programming Agent Service

A Harness MCP is a local server program based on the Model Context Protocol (MCP). It exposes Codex Harness's layered context, skill system, and autonomous Agent capabilities to external AI clients (such as Claude Desktop, DeepSeek, etc.) in the form of MCP tools. Through this service, external AI can execute code, read and write files, call external tools in your local project, and complete complex programming tasks in a structured way.

✨ Core Features

• Layered Context Assembly — Drawing on the Codex Harness design, it layers base behavioral guidelines, user-level AGENTS.md, project-level AGENTS.md, and skill indexes. The workflow conventions can be freely edited by users and are not hardcoded into the program.

• Skill System — Supports defining standalone skills under the project .a_harness_mcp/skills/ directory, loading full instructions on demand via the get_skill tool to reduce context redundancy.

• Rich Built-in Toolset — Provides shell command execution, file read/write, directory browsing, patch application, image viewing, web search, MCP server management, and more.

• Codex Agent Integration — Includes a built-in codex tool that can directly delegate complex coding tasks to the Codex Agent, with timeout control and custom model support.

• External MCP Server Proxy — Through the mcp_servers.json configuration, third-party MCP servers (such as Excel, SSH, AMap, etc.) can be uniformly proxied and integrated into the tool list.

• Graphical Control Interface — Provides a PyQt5-based GUI program for configuring project directories, permission modes, host ports, model parameters, and viewing service logs and AI interaction records in real time.

• Lightweight Test Client — Includes mcp_client_test.py implemented purely with the standard library, requiring no third-party dependencies to verify service availability.

Related MCP server: MCP Server

🚀 Quick Start

Start the Server

# 启动 GUI 控制界面
python codex_mcp_gui.py

# 或直接启动 HTTP 服务（无 GUI）
python codex_mcp_server.py

Connect an MCP Client

The service provides an MCP Streamable HTTP endpoint at http://127.0.0.1:9999/mcp by default, supporting connections from any MCP-compatible client.

Verify with the Smoke Test Client

# 握手并列出所有可用工具
python mcp_client_test.py

# 调用 shell 工具执行 dir 命令
python mcp_client_test.py --tool shell --args '{"command":"dir"}'

# 调用 codex 工具执行编程任务
python mcp_client_test.py --tool codex --args '{"prompt":"读取当前目录所有 Python 文件并统计总行数"}'

Configure in Claude Desktop

Add the following to the Claude Desktop configuration file:

{
  "mcpServers": {
    "a-harness-mcp": {
      "url": "http://127.0.0.1:9999/mcp"
    }
  }
}

📦 Available Tools

🧩 Skill System (Skills)

Skills are project-level reusable capability units stored in .a_harness_mcp/skills/<skill-name>/SKILL.md.

Each skill file declares metadata using frontmatter:

---
name: pdf-analyzer
description: 提取 PDF 文档中的表格和关键信息，适用于财务报告分析
---

# PDF 分析技能

## 使用场景
...

When external AI initializes, only the skill's name and description are loaded as an index; the full body is fetched on demand via get_skill, greatly reducing context window usage.

🎛️ Permission Modes

Permission modes can be switched via the GUI dropdown menu or service startup parameters.

📁 Layered Context Assembly Mechanism

When the service starts, it automatically assembles the following context and injects it into the external AI as initial instructions:

1. Base Behavioral Guidelines — Built-in Codex-style guidelines (tool specifications, autonomy, quality requirements)

2. User-level Workflow Conventions — ~/.a_harness_mcp/AGENTS.md (a default template is auto-generated on first run and can be freely edited)

3. Project-level Workflow Conventions — <project>/AGENTS.md or <project>/.a_harness_mcp/AGENTS.md (takes priority over the user level)

4. Skill Index — Scans the .a_harness_mcp/skills/ directory and aggregates the names and descriptions of all skills

🔌 External MCP Server Proxy

Through the mcp_servers.json configuration file, third-party MCP servers can be proxied into this service:

[
  {
    "name": "excel",
    "enabled": true,
    "config": {
      "mcpServers": {
        "excel": {
          "command": "npx",
          "args": ["-y", "@zhiweixu/excel-mcp-server"],
          "env": { "CACHE_MAX_AGE": "1" },
          "type": "stdio"
        }
      }
    }
  }
]

Proxied tools are uniformly registered into the tool list, and external AI can call them directly.

🧪 Development and Testing

Installing Dependencies

pip install PyQt5

Running Tests

# 启动服务（GUI 或非 GUI 模式）
python codex_mcp_gui.py

# 另开终端执行冒烟测试
python mcp_client_test.py

🗂️ Project Structure

.
├── A Harness MCP.exe       # PyInstaller 打包的可执行文件
├── codex_mcp_gui.py        # PyQt5 GUI 控制界面
├── codex_mcp_server.py     # MCP HTTP 服务核心实现
├── context.py              # 分层上下文装配器
├── mcp_plugins.py          # 外部 MCP 服务器代理与插件管理
├── mcp_client_test.py      # 纯标准库 MCP 客户端冒烟测试
├── mcp_servers.json        # 外部 MCP 服务器配置
└── codex_mcp_gui_config.json # GUI 配置文件（项目目录、端口、权限模式等）

📄 License

MIT

🤝 Contributing

Issues and Pull Requests are welcome. Before submitting code, please ensure:

• Existing code style is followed

• New features come with corresponding test cases

• Related documentation is updated

Made with ❤️ for local AI Agent development.