516e1479c6
Research conducted on modern AI coding assistants (Cursor, GitHub Copilot, Cline,
Aider, Windsurf, Replit Agent) to understand architecture patterns, context management,
code editing workflows, and tool use protocols.
Key Decision: Pivoted from building full CLI (40-50h) to validation-driven MCP-first
approach (10-15h). Build 5 core CODEX MCP tools that work with ANY coding assistant,
validate adoption over 2-4 weeks, then decide on full CLI if demand proven.
Files:
- research/ai-systems/modern-coding-assistants-architecture.md (comprehensive research)
- research/ai-systems/codex-coding-assistant-implementation-plan.md (original CLI plan, preserved)
- research/ai-systems/codex-mcp-tools-implementation-plan.md (approved MCP-first plan)
- ideas/registry.json (updated with approved MCP tools proposal)
Architech Validation: APPROVED with pivot to MCP-first approach
Human Decision: Approved (pragmatic validation-driven development)
Next: Begin Phase 1 implementation (10-15 hours, 5 core MCP tools)
🤖 Generated with CODEX Research System
Co-Authored-By: The Archivist <archivist@codex.svrnty.io>
Co-Authored-By: The Architech <architech@codex.svrnty.io>
Co-Authored-By: Mathias Beaulieu-Duncan <mat@svrnty.io>
189 lines
4.6 KiB
Markdown
189 lines
4.6 KiB
Markdown
# Adding CODEX MCP Server to Claude Code CLI
|
|
|
|
This guide shows how to integrate the CODEX MCP Server with Claude Code CLI (in WebStorm or standalone).
|
|
|
|
## Prerequisites
|
|
|
|
- .NET 8.0 SDK installed
|
|
- Claude Code CLI installed and configured
|
|
- OpenHarbor.MCP.Server cloned/copied to your system
|
|
|
|
## One-Time Setup
|
|
|
|
### 1. Build the CODEX MCP Server
|
|
|
|
```bash
|
|
cd /home/svrnty/codex/OpenHarbor.MCP.Server
|
|
dotnet build samples/CodexMcpServer/CodexMcpServer.csproj
|
|
```
|
|
|
|
### 2. Add to Claude Code CLI
|
|
|
|
```bash
|
|
# Add CODEX MCP server with HTTP transport
|
|
claude mcp add --transport stdio --scope user codex \
|
|
dotnet -- run --project /home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
**Command Breakdown:**
|
|
- `--transport stdio` - Use stdin/stdout communication (required for .NET console apps)
|
|
- `--scope user` - Available across all projects for this user (alternatives: `local`, `project`)
|
|
- `codex` - The name of the MCP server (used in CLI commands)
|
|
- `dotnet -- run --project <path>` - Command to start the server
|
|
|
|
### 3. Verify Setup
|
|
|
|
```bash
|
|
# List all MCP servers
|
|
claude mcp list
|
|
|
|
# View CODEX server details
|
|
claude mcp get codex
|
|
```
|
|
|
|
**Expected Output:**
|
|
```
|
|
codex:
|
|
Command: dotnet
|
|
Args: [run, --project, /home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer]
|
|
Transport: stdio
|
|
Scope: user
|
|
```
|
|
|
|
## Usage in Claude Code CLI
|
|
|
|
### Interactive Mode
|
|
|
|
```bash
|
|
# Start Claude in interactive mode
|
|
claude
|
|
|
|
# Claude will automatically discover the CODEX tools
|
|
# You can now ask questions like:
|
|
# "Search CODEX for documents about neural networks"
|
|
# "List all documents in CODEX"
|
|
# "Get tags from CODEX"
|
|
```
|
|
|
|
### Project Mode (WebStorm)
|
|
|
|
When using Claude Code CLI in WebStorm, the CODEX MCP server is automatically available:
|
|
|
|
1. Open WebStorm
|
|
2. Open Claude Code panel
|
|
3. Ask Claude to search CODEX:
|
|
- "Search my CODEX knowledge base for information about MCP"
|
|
- "List recent documents from CODEX"
|
|
- "What tags are available in CODEX?"
|
|
|
|
## Available Tools
|
|
|
|
The CODEX MCP server exposes 6 tools:
|
|
|
|
| Tool | Description | Parameters |
|
|
|------|-------------|------------|
|
|
| `search_codex` | Semantic/keyword search | `query` (string) |
|
|
| `get_document` | Retrieve document by ID | `id` (string) |
|
|
| `list_documents` | List all documents with pagination | `page` (int), `pageSize` (int) |
|
|
| `search_by_tag` | Filter documents by tag | `tag` (string) |
|
|
| `get_document_sections` | Get document sections | `id` (string) |
|
|
| `list_tags` | List all available tags | None |
|
|
|
|
## Troubleshooting
|
|
|
|
### Server Not Responding
|
|
|
|
```bash
|
|
# Test the server manually
|
|
echo '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | \
|
|
dotnet run --project /home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
**Expected:** JSON response listing all 6 tools
|
|
|
|
### CODEX API Connection Errors
|
|
|
|
The tools will return errors if CODEX API is not running:
|
|
|
|
```
|
|
Error: Connection refused (localhost:5050)
|
|
```
|
|
|
|
**Solution:** Start your CODEX API service:
|
|
```bash
|
|
# Start CODEX API (adjust path as needed)
|
|
cd /path/to/CODEX
|
|
dotnet run --project src/Codex.Api
|
|
```
|
|
|
|
### Removing the Server
|
|
|
|
```bash
|
|
# Remove CODEX MCP server from CLI
|
|
claude mcp remove codex
|
|
|
|
# Verify removal
|
|
claude mcp list
|
|
```
|
|
|
|
## Testing End-to-End
|
|
|
|
Run the test script to verify everything works:
|
|
|
|
```bash
|
|
cd /home/svrnty/codex/OpenHarbor.MCP.Server
|
|
python3 test_mcp_server.py
|
|
```
|
|
|
|
**Expected:** All 10 tests should pass (tools return proper JSON-RPC responses)
|
|
|
|
## Advanced Configuration
|
|
|
|
### Scopes
|
|
|
|
- **user** (recommended): Available globally for your user account
|
|
- **local**: Available only in current directory
|
|
- **project**: Available only in current project
|
|
|
|
```bash
|
|
# Change scope
|
|
claude mcp remove codex
|
|
claude mcp add --transport stdio --scope project codex \
|
|
dotnet -- run --project /home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
### Using Absolute Paths
|
|
|
|
For reliability, use absolute paths:
|
|
|
|
```bash
|
|
claude mcp add --transport stdio --scope user codex \
|
|
/usr/bin/dotnet -- run --project /home/svrnty/codex/OpenHarbor.MCP.Server/samples/CodexMcpServer
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. **Start CODEX API** (if you want to test with real data):
|
|
```bash
|
|
cd /path/to/CODEX
|
|
dotnet run --project src/Codex.Api
|
|
```
|
|
|
|
2. **Ask Claude to search CODEX:**
|
|
```
|
|
"Search CODEX for documents about clean architecture"
|
|
```
|
|
|
|
3. **Explore other tools:**
|
|
```
|
|
"List all tags in CODEX"
|
|
"Get document sections for document ID xyz123"
|
|
```
|
|
|
|
## Reference
|
|
|
|
- [Claude Code CLI Documentation](https://docs.claude.com/en/docs/claude-code)
|
|
- [Model Context Protocol Spec](https://modelcontextprotocol.io)
|
|
- [OpenHarbor.MCP README](README.md)
|
|
- [CODEX Documentation](../CODEX/README.md)
|