# 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)