svrnty-mcp-server/QUICK-START.md

CODEX MCP Server - Quick Start

Get your CODEX knowledge base connected via HTTP in 2 minutes.

TL;DR

# 1. Start CODEX API
cd /home/svrnty/codex/CODEX
dotnet run --project src/Codex.Api
# Listens on http://localhost:5099

# 2. Start CODEX MCP Server (HTTP mode)
cd /home/svrnty/codex/Svrnty.MCP.Server
dotnet run --project samples/CodexMcpServer
# Listens on http://localhost:5050

# 3. Test the server
curl http://localhost:5050/health

# 4. List available tools
curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}'

What You Get

6 tools accessible via HTTP for interacting with your CODEX knowledge base:

1. search_codex - Semantic search across all documents
2. get_document - Retrieve specific document by ID
3. list_documents - Browse all documents with pagination
4. search_by_tag - Filter by tags
5. get_document_sections - Get structured sections
6. list_tags - View all available tags

HTTP Endpoints

Base URL: http://localhost:5050

• POST /mcp/invoke - Main MCP JSON-RPC endpoint
• GET /health - Health check endpoint

Example Tool Calls

Once the server is running, you can call tools via HTTP:

Search CODEX

curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "1",
    "params": {
      "name": "search_codex",
      "arguments": {
        "query": "neural networks",
        "maxResults": 5
      }
    }
  }'

Get Document

curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "2",
    "params": {
      "name": "get_document",
      "arguments": {
        "documentId": "abc123"
      }
    }
  }'

List Tags

curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": "3"
  }'

Architecture (HTTP Mode)

┌─────────────────┐
│   MCP Client    │
│ (App/Gateway)   │
└────────┬────────┘
         │ HTTP POST
         │ (JSON-RPC 2.0)
         ▼
┌─────────────────┐
│ CODEX MCP Server│
│  (6 tools)      │
│ Port 5050       │
└────────┬────────┘
         │ HTTP REST
         ▼
┌─────────────────┐
│   CODEX API     │
│ Port 5099       │
└─────────────────┘

Requirements

• .NET 8.0 SDK
• CODEX API running at http://localhost:5099 (for real data)

Using with MCP Gateway

For production deployments with load balancing and multiple clients:

# Terminal 1: Start CODEX API
cd /home/svrnty/codex/CODEX
dotnet run --project src/Codex.Api

# Terminal 2: Start CODEX MCP Server
cd /home/svrnty/codex/Svrnty.MCP.Server
dotnet run --project samples/CodexMcpServer

# Terminal 3: Start MCP Gateway
cd /home/svrnty/codex/Svrnty.MCP.Gateway
dotnet run --project samples/CodexMcpGateway
# Gateway listens on http://localhost:8080
# Routes requests to http://localhost:5050

See Svrnty.MCP.Gateway for gateway configuration.

Troubleshooting

Health check fails

Solution: Verify the server is running:

curl -v http://localhost:5050/health

Expected response:

{"status":"Healthy","service":"MCP Server","timestamp":"..."}

Connection refused errors when using tools

Solution: Start CODEX API:

cd /home/svrnty/codex/CODEX
dotnet run --project src/Codex.Api

Verify it's running:

curl http://localhost:5099/health

Port already in use

Solution: Check what's using port 5050:

lsof -i :5050

Stop the conflicting process or configure a different port in appsettings.json.

Testing Without CODEX API

The MCP server works even if CODEX API isn't running - it will return proper error messages:

curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}'

Expected: JSON listing all 6 tools (even without CODEX API running)

Configuration

Edit samples/CodexMcpServer/appsettings.json:

{
  "Mcp": {
    "Transport": {
      "Type": "Http",
      "Port": 5050
    },
    "Codex": {
      "ApiBaseUrl": "http://localhost:5099"
    }
  }
}

Next Steps

1. Full integration guide: See INTEGRATION-GUIDE.md
2. Architecture details: See README.md
3. Gateway setup: See Svrnty.MCP.Gateway
4. Development: See docs/module-design.md

---

Legacy Support: Claude Desktop (Stdio Mode)

For local Claude Desktop integration, stdio mode is still available:

# Run in stdio mode
dotnet run --project samples/CodexMcpServer -- --stdio

Claude Desktop Configuration (~/.claude/config.json):

{
  "mcpServers": {
    "codex": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/home/svrnty/codex/Svrnty.MCP.Server/samples/CodexMcpServer/CodexMcpServer.csproj",
        "--",
        "--stdio"
      ],
      "transport": "stdio"
    }
  }
}

Note: HTTP mode is recommended for production deployments. Stdio mode is for local development and Claude Desktop integration only.

---

Files Reference

File	Purpose
QUICK-START.md	This file (2-minute HTTP setup)
INTEGRATION-GUIDE.md	Detailed integration patterns
README.md	Complete documentation
HTTP-TRANSPORT-STANDARDIZATION.md	HTTP architecture guide

Support

• Issues: GitHub Issues
• MCP Spec: modelcontextprotocol.io
• HTTP Transport Guide: See HTTP-TRANSPORT-STANDARDIZATION.md