Skip to content

2.3.62 Satellite MCP Forge

Jump to bottom
av edited this page Jan 3, 2026 · 2 revisions

MCP Forge

Handle: mcpforge
URL: http://localhost:34651

Screenshot

MCP Forge (MCP Context Forge Gateway) is a powerful gateway, registry, and proxy for the Model Context Protocol (MCP) with a comprehensive web Admin UI. It enables centralized management, federation, and discovery of multiple MCP servers into a single composable catalog.

Key Features:

  • Multi-transport support: HTTP/JSON-RPC, WebSocket, Server-Sent Events (SSE), STDIO
  • Web Admin UI: Intuitive interface for managing MCP servers, tools, resources, prompts, and gateways
  • Federation & Discovery: Aggregate multiple MCP servers into one unified catalog
  • Authentication: JWT + Basic Auth with configurable security (default: admin/changeme)
  • Flexible Database: SQLite (default), PostgreSQL, MySQL, or MariaDB
  • Redis Caching: Optional caching layer for enhanced performance
  • Protocol Enforcement: Health monitoring and registry centralization
  • Comprehensive Audit: Full audit trails with metadata tracking
  • AI Integration: Works with LangChain, LangGraph, CrewAI, Claude Desktop, GitHub Copilot, Cline, Continue, and more
  • Multi-architecture: Supports amd64, arm64, and s390x

⚠️ Beta Release: This is version 1.0.0-BETA-1. Features and APIs may change.

Starting

# Pull the image
harbor pull mcpforge

# Start MCP Forge
harbor up mcpforge --open
  • Access the Admin UI at http://localhost:34651
  • Default credentials: admin / changeme
  • For first-time setup, navigate to the Admin UI to:
    • Register MCP servers
    • Configure tools and resources
    • Set up gateways and federation
    • Review system health and audit logs

Configuration

Environment Variables

Following options can be set via harbor config:

# Main UI/API port
HARBOR_MCPFORGE_HOST_PORT          34651

# Container image
HARBOR_MCPFORGE_IMAGE              ghcr.io/ibm/mcp-context-forge
HARBOR_MCPFORGE_VERSION            1.0.0-BETA-1

# Database configuration
# SQLite (default - requires no additional setup)
HARBOR_MCPFORGE_DATABASE_URL       sqlite:////app/data/mcp.db
# PostgreSQL example:
# HARBOR_MCPFORGE_DATABASE_URL     postgresql://user:pass@host:5432/mcpforge
# MySQL example:
# HARBOR_MCPFORGE_DATABASE_URL     mysql://user:pass@host:3306/mcpforge

# JWT authentication
HARBOR_MCPFORGE_JWT_SECRET         harbor-mcpforge-secret-change-me
HARBOR_MCPFORGE_JWT_AUDIENCE       mcpgateway-api
HARBOR_MCPFORGE_JWT_ISSUER         mcpgateway

# Basic authentication
HARBOR_MCPFORGE_BASIC_AUTH_USER    admin
HARBOR_MCPFORGE_BASIC_AUTH_PASSWORD changeme

# Authentication settings
# Set to "true" if exposing externally!
HARBOR_MCPFORGE_AUTH_REQUIRED      false

# Platform administrator
HARBOR_MCPFORGE_ADMIN_EMAIL        admin@example.com
HARBOR_MCPFORGE_ADMIN_PASSWORD     changeme
HARBOR_MCPFORGE_ADMIN_FULL_NAME    Platform Administrator

Database Backend Options

MCP Forge supports multiple database backends:

SQLite (Default)

  • Zero configuration required
  • Perfect for development and small deployments
  • Data stored in mcpforge/data/mcp.db 
HARBOR_MCPFORGE_DATABASE_URL="sqlite:////app/data/mcp.db"

PostgreSQL

  • Recommended for production deployments
  • Better performance with multiple concurrent users
HARBOR_MCPFORGE_DATABASE_URL="postgresql://user:password@harbor.postgres:5432/mcpforge"

MySQL / MariaDB

  • Alternative production database option
HARBOR_MCPFORGE_DATABASE_URL="mysql://user:password@harbor.mysql:3306/mcpforge"

Authentication Setup

⚠️ Security Warning: Default authentication is disabled (AUTH_REQUIRED=false) for localhost development. Always enable authentication when exposing MCP Forge externally.

Enable Authentication:

# Set via harbor config or in mcpforge/override.env
HARBOR_MCPFORGE_AUTH_REQUIRED="true"

Change Default Credentials:

# Update Basic Auth credentials
HARBOR_MCPFORGE_BASIC_AUTH_USER="your-username"
HARBOR_MCPFORGE_BASIC_AUTH_PASSWORD="strong-password-here"

# Update Admin credentials
HARBOR_MCPFORGE_ADMIN_EMAIL="admin@yourdomain.com"
HARBOR_MCPFORGE_ADMIN_PASSWORD="strong-admin-password"

# Update JWT secret (use a strong random string)
HARBOR_MCPFORGE_JWT_SECRET="your-secure-jwt-secret-here"

Volumes

MCP Forge persists data in the following directories:

  • mcpforge/data/ - SQLite database (if using SQLite backend)
  • Additional configuration files can be mounted as needed

Usage

Accessing the Admin UI

  1. Start MCP Forge: harbor up mcpforge --open
  2. Navigate to http://localhost:34651
  3. Log in with default credentials: admin / changeme

Basic Operations

Registering MCP Servers:

  1. Navigate to Servers in the Admin UI
  2. Click Add Server
  3. Configure transport type (HTTP, WebSocket, SSE, or STDIO)
  4. Provide connection details (URL, port, authentication)
  5. Save and test connection

Managing Tools:

  • View all available tools from registered servers
  • Enable/disable specific tools
  • Configure tool permissions and rate limits
  • Monitor tool usage and performance

Managing Resources:

  • Access resources exposed by MCP servers
  • Configure resource caching policies
  • Set up resource access controls

Managing Prompts:

  • Create and manage prompt templates
  • Version control for prompts
  • Share prompts across servers

Gateway Configuration:

  • Set up federation between multiple MCP Forge instances
  • Configure load balancing
  • Enable service discovery

Audit & Monitoring:

  • View comprehensive audit logs
  • Monitor server health and uptime
  • Track API usage and performance metrics

Integration with Harbor

MCP Services Integration

MCP Forge works seamlessly with other MCP services in Harbor:

With MetaMCP:

# Run both services
harbor up mcpforge metamcp

# Configure MetaMCP servers in MCP Forge
# Point MCP Forge to http://harbor.metamcp:8000

With MCP Inspector:

# Use MCP Inspector for debugging
harbor up mcpforge mcp-inspector

# Configure MCP Forge as a server in MCP Inspector
# Server URL: http://harbor.mcpforge:4444

Troubleshooting

Check Logs

# View MCP Forge logs
harbor logs mcpforge

# Follow logs in real-time
harbor logs -f mcpforge

Connection Issues

Cannot access Admin UI:

# Check if service is running
harbor ps

# Check port binding
curl http://localhost:34651/health

# Restart service
harbor restart mcpforge

MCP servers not connecting:

  • Verify server URLs are accessible from within the container
  • Use harbor.<service> format for Harbor services (e.g., http://harbor.ollama:11434)
  • Check authentication credentials if AUTH_REQUIRED is enabled
  • Review audit logs in the Admin UI for connection errors

Database Issues

SQLite database locked:

# Stop the service
harbor down mcpforge

# Check for stale locks
rm -f mcpforge/data/mcp.db-shm mcpforge/data/mcp.db-wal

# Restart
harbor up mcpforge

Database migration errors:

# View detailed logs
harbor logs mcpforge | grep -i migration

# If using PostgreSQL/MySQL, ensure the database exists
# and user has proper permissions

# For SQLite, ensure the data directory is writable
chmod 755 mcpforge/data

Performance Issues

Slow response times:

  • Enable Redis caching (see Redis Caching Configuration above)
  • Consider upgrading from SQLite to PostgreSQL for better concurrency
  • Review audit logs for slow queries
  • Check network latency to registered MCP servers

High memory usage:

  • Reduce number of concurrent server connections
  • Adjust cache TTL settings
  • Monitor in Admin UI → System → Performance

Authentication Problems

Cannot log in:

# Verify credentials
grep ADMIN mcpforge/override.env

# Reset admin password
# Edit mcpforge/override.env and update:
HARBOR_MCPFORGE_ADMIN_PASSWORD="new-password"

# Restart service
harbor restart mcpforge

JWT token errors:

  • Ensure JWT_SECRET is consistent across restarts
  • Check token expiration settings
  • Review browser console for detailed errors

Health Check Failures

# Manual health check
curl -f http://localhost:34651/health

# Check dependencies
harbor ps  # Ensure database/redis are running

# Review startup logs
harbor logs mcpforge | head -50

Links

Related Harbor Services

  • MetaMCP - MCP server for managing MCP servers
  • MCP Inspector - Debugging tool for MCP protocol
  • MCPO - MCP Observatory for monitoring
  • Ollama - Local LLM backend
  • LiteLLM - Unified LLM proxy

Home | CLI Reference | Services | Adding New Service | Compatibility

Clone this wiki locally