svrnty-mcp-server/INTEGRATION-GUIDE.md

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
• Svrnty.MCP.Server cloned/copied to your system

One-Time Setup

1. Build the CODEX MCP Server

cd /home/svrnty/codex/Svrnty.MCP.Server
dotnet build samples/CodexMcpServer/CodexMcpServer.csproj

2. Add to Claude Code CLI

# Add CODEX MCP server with HTTP transport
claude mcp add --transport stdio --scope user codex \
  dotnet -- run --project /home/svrnty/codex/Svrnty.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

# 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/Svrnty.MCP.Server/samples/CodexMcpServer]
  Transport: stdio
  Scope: user

Usage in Claude Code CLI

Interactive Mode

# 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

# Test the server manually
echo '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | \
  dotnet run --project /home/svrnty/codex/Svrnty.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:

# Start CODEX API (adjust path as needed)
cd /path/to/CODEX
dotnet run --project src/Codex.Api

Removing the Server

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

cd /home/svrnty/codex/Svrnty.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

# Change scope
claude mcp remove codex
claude mcp add --transport stdio --scope project codex \
  dotnet -- run --project /home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer

Using Absolute Paths

For reliability, use absolute paths:

claude mcp add --transport stdio --scope user codex \
  /usr/bin/dotnet -- run --project /home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer

Next Steps

1. Start CODEX API (if you want to test with real data):

   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
• Model Context Protocol Spec
• Svrnty.MCP README
• CODEX Documentation