opalserve

v3.0.1

Published

a day ago

The control plane for your team's AI tools — share MCP servers, knowledge bases, and usage analytics across your engineering team

0High
0Medium
0Low

adityaai_dev

mcp model-context-protocol tool-registry ai-tools cli discovery aggregator llm claude cursor

OpalServe is an open-source platform that gives engineering teams a single place to register, discover, and govern the MCP (Model Context Protocol) servers their AI coding tools depend on. Instead of every developer manually configuring Claude Desktop, Cursor, Codex, or Windsurf with scattered server definitions, OpalServe provides a centralized registry with shared knowledge bases, usage analytics, role-based access control, and a built-in MCP gateway -- so your team's AI tools stay consistent, observable, and secure.

Feature Highlights

| | Feature | Description | |---|---|---| | :books: | Team MCP Registry | Admin registers servers once; every developer pulls them with opalserve sync | | :brain: | Shared Knowledge Base | Upload architecture docs, coding standards, and API specs -- AI tools query them automatically via MCP | | :bar_chart: | Usage Analytics Dashboard | React SPA showing tool calls, token usage, active users, and error rates in real time | | :lock: | Auth & Access Control | User accounts, JWT tokens, API keys, rate limits, and per-role tool permissions | | :electric_plug: | GitHub + Slack Integrations | Webhooks auto-update context; Slack slash commands for search and notifications | | :globe_with_meridians: | MCP Gateway | OpalServe itself is an MCP server -- connect any AI client to access every tool from one endpoint | | :art: | Beautiful CLI | Interactive setup wizard, gradient banners, color-coded tables, 20+ commands | | :seedling: | 100% Open Source | MIT licensed, self-host for free, no vendor lock-in |

Architecture

 ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
 │   GitHub     │ │   Slack      │ │  Filesystem  │ │  PostgreSQL  │
 │  MCP Server  │ │  MCP Server  │ │  MCP Server  │ │  MCP Server  │
 └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
        │                │                │                │
        └────────────────┼────────────────┼────────────────┘
                         │   MCP Protocol (stdio / SSE)
                         │
              ┌──────────┴──────────────────────────────┐
              │          OpalServe Team Server           │
              │                                         │
              │  ┌─────────────┐  ┌──────────────────┐  │
              │  │ MCP Server  │  │  Shared Knowledge │  │
              │  │ Registry    │  │  Base (FTS)       │  │
              │  └─────────────┘  └──────────────────┘  │
              │  ┌─────────────┐  ┌──────────────────┐  │
              │  │ Usage       │  │  Auth / API Keys  │  │
              │  │ Analytics   │  │  Rate Limiting    │  │
              │  └─────────────┘  └──────────────────┘  │
              │  ┌─────────────┐  ┌──────────────────┐  │
              │  │ MCP Gateway │  │  React Dashboard  │  │
              │  │ (stdio/SSE) │  │  (/dashboard)     │  │
              │  └─────────────┘  └──────────────────┘  │
              │                                         │
              │  SQLite DB ── Fastify HTTP API (:3456)   │
              └──────────────────┬──────────────────────┘
                                 │
              HTTPS API + MCP Protocol (stdio / SSE)
                                 │
          ┌──────────────────────┼──────────────────────┐
          │                      │                      │
 ┌────────┴─────────┐  ┌────────┴─────────┐  ┌────────┴─────────┐
 │  Dev A            │  │  Dev B            │  │  Dev C            │
 │  Claude Code      │  │  Cursor           │  │  Codex / Windsurf │
 │  opalserve sync   │  │  opalserve sync   │  │  opalserve sync   │
 └──────────────────┘  └──────────────────┘  └──────────────────┘

Quick Start

# 1. Install globally
npm install -g opalserve

# 2. Run the interactive setup wizard
opalserve init

# 3. Start the server
opalserve start

# 4. Register your first MCP server
opalserve server add --name files --stdio "npx -y @modelcontextprotocol/server-filesystem ."

# 5. Discover available tools
opalserve tools search "read file"

Tip: OpalServe runs on port 3456 by default. Visit http://localhost:3456/dashboard after starting.

Team Mode Setup

Team mode turns OpalServe into a shared server that your entire engineering org connects to.

1. Initialize the team server

opalserve admin init

This creates an admin account, generates encryption keys, and prepares the SQLite database.

2. Configure team mode

Edit opalserve.config.json and set the mode:

{
  "mode": "team-server",
  "port": 3456,
  "host": "0.0.0.0"
}

3. Start the server

opalserve start

4. Invite team members

opalserve admin invite [email protected]
opalserve admin invite [email protected]

5. Developers connect

On each developer's machine:

npm install -g opalserve

# Login to the team server
opalserve login

# Pull all registered servers to local config
opalserve sync

6. Manage access

# Set rate limits by role
opalserve admin limits --set developer:calls_per_hour:500

# Set tool permissions
opalserve admin permissions --set developer:filesystem:*:allow

Knowledge Base

The knowledge base lets you upload documents that become searchable context for every AI tool connected through OpalServe.

Adding documents

# Upload architecture docs
opalserve context add ./docs/architecture.md

# Upload API specifications
opalserve context add ./docs/api-spec.md

# Upload coding standards
opalserve context add ./docs/coding-standards.md

Searching context

# Search by natural language query
opalserve context search "authentication flow"

# List all uploaded documents
opalserve context list

# Remove a document
opalserve context remove <document-id>

When connected via the MCP gateway, AI tools like Claude Desktop can automatically search the knowledge base to ground their responses in your team's actual documentation.

Admin Dashboard

OpalServe ships with a built-in React SPA accessible at /dashboard when the server is running.

The dashboard provides:

Usage overview -- charts for tool calls, token consumption, and active users over time
Server monitoring -- live status of every registered MCP server with health indicators
User management -- view team members, roles, and activity
Tool browser -- searchable catalog of all discovered tools across servers
Knowledge base manager -- upload, browse, and remove context documents
Settings -- API key management, integration configuration, rate limits

http://localhost:3456/dashboard

The dashboard is available in team-server mode. Authentication is required for all management operations.

CLI Commands

| Command | Description | |---|---| | opalserve init | Interactive setup wizard -- configures mode, port, and first server | | opalserve start | Start the registry server (HTTP API + MCP gateway) | | opalserve status | Show server status, connected servers, and tool counts | | opalserve health | Health check all registered servers | | opalserve health --server <name> | Health check a specific server | | opalserve login | Authenticate with a team server | | opalserve logout | Clear stored credentials | | opalserve whoami | Show current authenticated user info | | opalserve sync | Pull team server configurations to local machine | | opalserve server list | List all registered MCP servers | | opalserve server add | Register a new MCP server (stdio, SSE, or streamable-http) | | opalserve server remove <name> | Remove a registered server | | opalserve tools list | List all discovered tools across servers | | opalserve tools search <query> | Search for tools by natural language query | | opalserve context add <file> | Upload a file to the shared knowledge base | | opalserve context list | List all context documents | | opalserve context search <query> | Search the knowledge base | | opalserve context remove <id> | Remove a context document | | opalserve admin init | Initialize team mode with an admin user | | opalserve admin stats | Show usage statistics for the team | | opalserve admin users | List all team members | | opalserve admin invite <email> | Invite a user to the team | | opalserve admin limits | View and manage rate limits | | opalserve admin permissions | View and manage tool permissions |

HTTP API

OpalServe exposes a RESTful API under /api/v1. All endpoints return JSON.

Health

curl http://localhost:3456/api/v1/health

Servers

# List all servers
curl http://localhost:3456/api/v1/servers

# Register a new server
curl -X POST http://localhost:3456/api/v1/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "transport": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }'

# Remove a server
curl -X DELETE http://localhost:3456/api/v1/servers/filesystem

# Health check a specific server
curl http://localhost:3456/api/v1/servers/filesystem/health

Tools

# List all tools
curl http://localhost:3456/api/v1/tools

# Search tools
curl "http://localhost:3456/api/v1/tools/search?q=read+file&limit=5"

# Call a tool
curl -X POST http://localhost:3456/api/v1/tools/filesystem__read_file/call \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"path": "./README.md"}}'

Authentication (team mode)

# Register
curl -X POST http://localhost:3456/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "...", "name": "Alice"}'

# Login
curl -X POST http://localhost:3456/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "..."}'

# Get current user
curl http://localhost:3456/api/v1/auth/me \
  -H "Authorization: Bearer <token>"

# Create API key
curl -X POST http://localhost:3456/api/v1/auth/keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline"}'

Knowledge Base (team mode)

# Upload a document
curl -X POST http://localhost:3456/api/v1/context/documents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Architecture", "content": "...", "type": "markdown"}'

# Search documents
curl "http://localhost:3456/api/v1/context/search?q=authentication+flow" \
  -H "Authorization: Bearer <token>"

Usage Stats (team mode)

# Overview
curl http://localhost:3456/api/v1/stats/overview \
  -H "Authorization: Bearer <token>"

Library Usage

Use OpalServe programmatically in your Node.js applications:

import {
  OpalServeRegistry,
  McpGateway,
  KnowledgeBase,
  UsageTracker,
} from 'opalserve';

// Create the registry with server definitions
const registry = await OpalServeRegistry.create({
  servers: [
    {
      name: 'filesystem',
      transport: {
        type: 'stdio',
        command: 'npx',
        args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
      },
    },
    {
      name: 'github',
      transport: {
        type: 'sse',
        url: 'https://mcp-github.example.com/sse',
      },
    },
  ],
});

// Start the registry -- connects to all servers and indexes tools
await registry.start();

// List all discovered tools
const tools = registry.listTools();
console.log(`Discovered ${tools.length} tools`);

// Search with natural language
const results = registry.searchTools('read file contents');
for (const result of results) {
  console.log(`${result.tool.name} (score: ${result.score})`);
}

// Graceful shutdown
await registry.stop();

MCP Gateway

OpalServe can act as an MCP server itself, exposing every registered tool through a single endpoint. This lets you point Claude Desktop, Cursor, or any MCP-compatible client at OpalServe instead of configuring each server individually.

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor

Add to your Cursor MCP settings:

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

Once connected, your AI client gains access to:

opalserve_search -- search across all registered tools by natural language query
opalserve_context_search -- search the shared knowledge base
All proxied tools -- every tool from every registered server, available through the single gateway

Integrations

GitHub

Set up GitHub webhooks to automatically update context when code changes:

# Add GitHub MCP server
opalserve server add --name github --stdio "npx -y @modelcontextprotocol/server-github"

# Configure webhook (point your repo's webhook to):
# POST http://your-server:3456/api/v1/webhooks/github

Environment variables:

GITHUB_TOKEN=ghp_...
GITHUB_WEBHOOK_SECRET=your-secret

Slack

Enable Slack integration for search commands and notifications:

# Add Slack MCP server
opalserve server add --name slack --stdio "npx -y @modelcontextprotocol/server-slack"

Configure your Slack app to send events and commands to:

Events:  POST http://your-server:3456/api/v1/slack/events
Commands: POST http://your-server:3456/api/v1/slack/commands

Environment variables:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=your-secret

Configuration

OpalServe is configured via opalserve.config.json in your project root or home directory.

{
  "mode": "local",
  "port": 3456,
  "host": "127.0.0.1",
  "servers": [
    {
      "name": "filesystem",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
      }
    }
  ]
}

| Option | Default | Description | |---|---|---| | mode | "local" | "local" for single-user, "team-server" for shared | | port | 3456 | HTTP API port | | host | "127.0.0.1" | Bind address (0.0.0.0 for team server) | | servers | [] | Array of MCP server configurations |

Modes: local (single developer, no auth) and team-server (multi-user with auth, analytics, knowledge base).

See the full configuration reference for all options.

Contributing

Contributions are welcome. To get started:

# Clone the repo
git clone https://github.com/adityaidev/opalserve.git
cd opalserve

# Install dependencies
pnpm install

# Start in dev mode (watch + auto-reload)
pnpm dev

# Type-check
pnpm typecheck

# Lint
pnpm lint

# Run tests
pnpm test

Please open an issue before submitting large PRs. Follow the existing code style -- strict TypeScript, Zod schemas for validation, and .js extensions in imports.

License

MIT -- 100% open source, free to self-host.

See LICENSE for details.