Documentation

Overview

ClaudeForge is a powerful orchestration platform for Model Context Protocol (MCP) servers. It acts as a transparent proxy between MCP clients and multiple MCP servers, providing sophisticated management capabilities through a web interface.

Key Features

• Transparent Proxying - Clients connect as if to a single MCP server
• Multiple Transport Support - stdio, SSE, and WebSocket protocols
• Permission Management - Granular control over tool access
• Web Dashboard - Real-time monitoring and configuration
• Session Management - Track and control client connections
• Hot Reload - Update configurations without downtime

Quick Install

Get ClaudeForge running in under a minute with our automated installer:

# Using curl
curl -sSL https://raw.githubusercontent.com/jpeggdev/claudeforge/main/install-remote.sh | bash

# Using wget
wget -qO- https://raw.githubusercontent.com/jpeggdev/claudeforge/main/install-remote.sh | bash

The installer will:

• Check and install Node.js 18+ if needed
• Download ClaudeForge to ~/claudeforge
• Install all dependencies
• Build the TypeScript project
• Set up as a user service (starts on login)
• Configure the web interface on port 8080

Architecture

ClaudeForge uses a modular architecture designed for flexibility and scalability:

┌─────────────┐
│  MCP Client │
└──────┬──────┘
       │ HTTP/SSE
       ▼
┌─────────────────────────────┐
│       ClaudeForge Proxy      │
│  ┌────────────────────────┐  │
│  │   Permission Manager   │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │    Server Manager      │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │     Log Manager        │  │
│  └────────────────────────┘  │
└───────────┬─────────────────┘
            │
    ┌───────┴────────┬────────┬────────┐
    ▼                ▼        ▼        ▼
┌──────┐        ┌──────┐ ┌──────┐ ┌──────┐
│Server│        │Server│ │Server│ │Server│
│(stdio)│       │(SSE) │ │(WS)  │ │...   │
└──────┘        └──────┘ └──────┘ └──────┘

Core Components

Proxy Server

The main server that handles incoming MCP client connections and routes requests to appropriate backend servers.

Server Manager

Manages lifecycle of connected MCP servers, including connection, disconnection, and health monitoring.

Permission Manager

Controls access to tools and resources based on configurable policies and session-specific rules.

Web Server

Provides the management interface and REST API for configuration and monitoring.

Configuration

Configuration File

ClaudeForge uses a JSON configuration file to define servers and settings:

{
  "port": 3000,
  "webPort": 8080,
  "defaultPermissions": "allow",
  "servers": [
    {
      "id": "filesystem",
      "name": "Filesystem Server",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "transport": "stdio",
      "env": {
        "DEBUG": "true"
      }
    },
    {
      "id": "github",
      "name": "GitHub Server",
      "endpoint": "http://localhost:3001/mcp/sse",
      "transport": "sse",
      "apiKey": "${GITHUB_API_KEY}"
    }
  ]
}

Server Configuration Options

Transport Types

stdio Transport

Launches a subprocess and communicates via standard input/output:

{
  "transport": "stdio",
  "command": "node",
  "args": ["./my-server.js"],
  "env": {
    "NODE_ENV": "production"
  }
}

SSE Transport

Connects to a server using Server-Sent Events:

{
  "transport": "sse",
  "endpoint": "http://localhost:3001/mcp/sse",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

WebSocket Transport

Connects via WebSocket protocol:

{
  "transport": "websocket",
  "endpoint": "ws://localhost:3002/mcp",
  "reconnect": true,
  "reconnectDelay": 5000
}

Permission System

ClaudeForge provides granular control over tool access with a flexible permission system.

Permission Levels

• Read - View tool information
• Write - Modify tool parameters
• Execute - Run the tool

Default Policies

{
  "defaultPermissions": "allow",  // or "deny"
  "permissions": {
    "filesystem": {
      "read_file": ["read", "execute"],
      "write_file": ["deny"],
      "delete_file": ["deny"]
    }
  }
}

Session-Based Permissions

Permissions can be modified per session through the web interface or API:

// Update permissions via API
fetch('/api/sessions/abc123/permissions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    'filesystem::read_file': true,
    'filesystem::write_file': false
  })
});

REST API Reference

Server Management

// Response
{
  "servers": [
    {
      "id": "filesystem",
      "name": "Filesystem Server",
      "status": "connected",
      "transport": "stdio",
      "tools": ["read_file", "write_file"],
      "resources": [],
      "prompts": []
    }
  ]
}

// Response
{
  "success": true,
  "message": "Server restarted successfully"
}

Session Management

// Response
{
  "sessions": [
    {
      "id": "session-123",
      "clientInfo": "Claude Desktop",
      "connectedAt": "2024-01-15T10:30:00Z",
      "permissions": {
        "filesystem::read_file": true,
        "filesystem::write_file": false
      }
    }
  ]
}

// Request
{
  "filesystem::read_file": true,
  "filesystem::write_file": false,
  "github::create_issue": true
}

// Response
{
  "success": true,
  "updated": 3
}

WebSocket API

Connect to ws://localhost:8080/ws for real-time updates:

Status Updates

{
  "type": "status",
  "servers": [
    {
      "id": "filesystem",
      "name": "Filesystem Server",
      "status": "connected",
      "error": null,
      "tools": 5,
      "resources": 2
    }
  ]
}

Session Events

{
  "type": "session",
  "event": "connected",
  "sessionId": "abc123",
  "clientInfo": "Claude Desktop"
}

Tool Execution Events

{
  "type": "tool_execution",
  "sessionId": "abc123",
  "serverId": "filesystem",
  "tool": "read_file",
  "timestamp": "2024-01-15T10:30:00Z",
  "duration": 125,
  "success": true
}

Running as a System Service

Linux (systemd)

# Install service
sudo ./services/linux/install-service.sh

# Manage service
sudo systemctl start claudeforge
sudo systemctl stop claudeforge
sudo systemctl restart claudeforge
sudo systemctl status claudeforge

# View logs
journalctl -u claudeforge -f

# Enable auto-start
sudo systemctl enable claudeforge

macOS (launchd)

# Install service
sudo ./services/macos/install-service.sh

# Manage service
sudo launchctl start com.claudeforge.server
sudo launchctl stop com.claudeforge.server

# View logs
tail -f /usr/local/var/log/claudeforge/stdout.log

Windows (Service)

# Run as Administrator
cd services\windows
.\install-service.ps1

# Manage service
net start ClaudeForge
net stop ClaudeForge
sc query ClaudeForge

Docker Deployment

Dockerfile

FROM node:18-alpine
WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --production

# Copy source
COPY . .
RUN npm run build

# Expose ports
EXPOSE 3000 8080

# Run
CMD ["node", "dist/index.js"]

Docker Compose

version: '3.8'
services:
  claudeforge:
    build: .
    ports:
      - "3000:3000"
      - "8080:8080"
    volumes:
      - ./config.json:/app/config.json
      - ./logs:/app/logs
    environment:
      - NODE_ENV=production
      - CLAUDEFORGE_CONFIG=/app/config.json
    restart: unless-stopped

Running with Docker

# Build image
docker build -t claudeforge .

# Run container
docker run -d \
  -p 3000:3000 \
  -p 8080:8080 \
  -v $(pwd)/config.json:/app/config.json \
  --name claudeforge \
  claudeforge

# View logs
docker logs -f claudeforge

Security Best Practices

Authentication

For production deployments, implement authentication:

// Example: Add basic auth middleware
app.use('/api', (req, res, next) => {
  const auth = req.headers.authorization;
  if (!auth || !verifyToken(auth)) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

TLS/SSL Configuration

Use a reverse proxy for HTTPS:

# nginx configuration
server {
    listen 443 ssl;
    server_name claudeforge.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
    }
}

Environment Variables

Store sensitive data in environment variables:

# .env file (never commit this)
GITHUB_API_KEY=ghp_xxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxx
CLAUDEFORGE_SECRET=random-secret-key

Firewall Rules

# Allow only local connections
sudo ufw allow from 127.0.0.1 to any port 3000
sudo ufw allow from 127.0.0.1 to any port 8080

# Or allow specific IPs
sudo ufw allow from 192.168.1.0/24 to any port 8080

Troubleshooting

Common Issues

Debug Mode

# Enable debug logging
export DEBUG=claudeforge:*
npm run dev

# Or in config.json
{
  "debug": true,
  "logLevel": "verbose"
}

Getting Help

• GitHub Issues: Report bugs
• Discussions: Ask questions
• Email: jpeggdev@gmail.com