Example: Multi-Server Setup

Aggregate tools from multiple MCP servers into a single OpalServe registry. This example shows a full team setup with 5+ servers.

Configuration File

Create opalserve.config.json:

{
  "mode": "team-server",
  "servers": [
    {
      "name": "files",
      "description": "Shared project files",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/opt/projects"]
      },
      "tags": ["files"]
    },
    {
      "name": "github",
      "description": "GitHub repositories and issues",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "ghp_xxx" }
      },
      "tags": ["code", "github"]
    },
    {
      "name": "slack",
      "description": "Slack workspace",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-slack"],
        "env": { "SLACK_BOT_TOKEN": "xoxb-xxx" }
      },
      "tags": ["communication"]
    },
    {
      "name": "search",
      "description": "Web search via Brave",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-brave-search"],
        "env": { "BRAVE_API_KEY": "xxx" }
      },
      "tags": ["search"]
    },
    {
      "name": "database",
      "description": "Production database (read-only)",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://readonly:pass@db.internal/prod"]
      },
      "tags": ["database"]
    },
    {
      "name": "browser",
      "description": "Browser automation for testing",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
      },
      "tags": ["testing", "browser"]
    }
  ],
  "gateway": {
    "port": 3456,
    "host": "0.0.0.0"
  },
  "auth": {
    "enabled": true,
    "jwtSecret": "use-OPALSERVE_JWT_SECRET-env-var",
    "apiKeys": true
  },
  "team": {
    "name": "Acme Engineering",
    "maxUsers": 50,
    "defaultRole": "developer"
  },
  "rateLimiting": {
    "enabled": true,
    "windowMs": 60000,
    "maxRequests": 100,
    "toolCallLimit": 50
  },
  "knowledgeBase": {
    "enabled": true,
    "maxDocuments": 500
  },
  "logging": {
    "level": "info"
  }
}

Environment variables

Do not hardcode API tokens in the config file. Use environment variables:

export GITHUB_TOKEN=ghp_xxx
export SLACK_BOT_TOKEN=xoxb-xxx
export BRAVE_API_KEY=xxx
export OPALSERVE_JWT_SECRET=$(openssl rand -hex 32)

Then reference them in the config or pass them via --env when adding servers.

Starting the Server

opalserve start

Output:

  OpalServe v3.0.0 (team-server mode)

  Connecting to 6 server(s)...

  files       connected   (12 tools)
  github      connected   (8 tools)
  slack       connected   (5 tools)
  search      connected   (3 tools)
  database    connected   (4 tools)
  browser     connected   (6 tools)

  HTTP API     http://0.0.0.0:3456
  Dashboard    http://0.0.0.0:3456/dashboard
  MCP Gateway  ready
  Auth:        enabled (JWT + API keys)

  38 tools available across 6 server(s)

Unified Search

Search across all 38 tools at once:

opalserve tools search "search"
# Returns: brave_web_search, search_repositories, search_files, search_code, ...

opalserve tools search "create"
# Returns: create_issue, create_pull_request, create_directory, send_message, ...

opalserve tools search "read"
# Returns: read_file, get_file_contents, read_multiple_files, query, ...

Use as MCP Gateway

Point Claude Desktop or any MCP client at OpalServe instead of configuring 6 separate servers:

{
  "mcpServers": {
    "opalserve": {
      "command": "opalserve",
      "args": ["start", "--mcp"]
    }
  }
}

Now your AI tool has access to all 38 tools from one connection. It can:

• Search GitHub repos and create issues
• Read and write files
• Send Slack messages
• Query the database
• Search the web
• Automate browser testing

All through a single MCP connection.

Adding the Knowledge Base

Upload your team's documentation so AI tools have context:

# Architecture docs
opalserve context add ./docs/architecture/ \
  --tags arch --pattern "*.md"

# Runbooks
opalserve context add ./docs/runbooks/ \
  --tags ops,runbook --pattern "*.md"

# API specs
opalserve context add ./docs/api/ \
  --tags api --pattern "*.md"

Now when a developer asks their AI tool "how do we deploy?", it can search the knowledge base and return your actual documentation.

Team Member Workflow

After the admin sets everything up, each team member runs:

# One-time setup
npm install -g opalserve
opalserve login https://opalserve.company.com

# Daily workflow
opalserve sync
# That's it. All 38 tools are available in their AI client.

Monitoring

The admin can track usage through the dashboard or CLI:

opalserve admin stats --period 7d

  Usage Statistics (last 7 days)

  Total requests:    4,231
  Tool calls:        1,847
  Active users:      12
  Unique tools used: 24

  Top tools:
    github:create_issue          312 calls
    files:read_file              289 calls
    github:search_repositories   201 calls
    search:brave_web_search      178 calls
    database:query               156 calls

Scaling Up

As your team grows, you can:

• Add more servers — opalserve server add at any time
• Increase rate limits — adjust per-user or global limits
• Set server-level permissions — restrict database access to senior devs
• Add integrations — GitHub webhooks for auto-context, Slack commands for tool search
• Scale horizontally — run multiple OpalServe instances behind a load balancer with a shared database