Team Setup

This guide walks you through setting up OpalServe as a team server, inviting developers, and getting everyone connected.

Prerequisites

• Node.js >= 20.0.0
• A machine accessible to your team (server, VM, or container)
• 10 minutes of setup time

Step 1 — Install OpalServe

On the machine that will run the team server:

npm install -g opalserve

Or use Docker:

docker pull ghcr.io/adityaidev/opalserve:latest

Step 2 — Initialize the Team Server

Run the admin initialization command:

opalserve admin init

The wizard will prompt you for:

  Initializing OpalServe team server...

  ? Admin email: admin@company.com
  ? Admin password: ********
  ? Team name: Acme Engineering
  ? HTTP API port: 3456

  Admin account created.
  JWT secret generated and stored.
  Config updated to team-server mode.

This creates:

• An admin user account
• A cryptographic JWT secret for token signing
• A configuration file set to team-server mode

Manual configuration

If you prefer to configure manually, see the team-server config example.

Step 3 — Register MCP Servers

Add the MCP servers your team will use:

# GitHub — for repo access, issues, PRs
opalserve server add \
  --name github \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_your_org_token \
  --description "GitHub repositories" \
  --tags code,github

# Filesystem — for shared documentation
opalserve server add \
  --name docs \
  --stdio "npx -y @modelcontextprotocol/server-filesystem /opt/team-docs" \
  --description "Engineering documentation" \
  --tags docs

# Slack — for team communication
opalserve server add \
  --name slack \
  --stdio "npx -y @modelcontextprotocol/server-slack" \
  --env SLACK_BOT_TOKEN=xoxb-your-bot-token \
  --description "Slack workspace" \
  --tags communication

# PostgreSQL — for database queries
opalserve server add \
  --name database \
  --stdio "npx -y @modelcontextprotocol/server-postgres postgresql://readonly:pass@db.internal/prod" \
  --description "Production database (read-only)" \
  --tags database

API Tokens

Use organization-level tokens rather than personal tokens. Store them as environment variables on the server rather than in the config file:

export GITHUB_TOKEN=ghp_org_token
export SLACK_BOT_TOKEN=xoxb_bot_token

Step 4 — Start the Server

opalserve start

You should see:

  OpalServe v3.0.0 (team-server mode)

  Connecting to 4 server(s)...

  github     connected   (8 tools)
  docs       connected   (12 tools)
  slack      connected   (5 tools)
  database   connected   (4 tools)

  HTTP API     http://0.0.0.0:3456
  Dashboard    http://0.0.0.0:3456/dashboard
  MCP Gateway  ready

  29 tools available across 4 server(s)
  Auth: enabled (JWT)

Running in production

For production deployments, use a process manager:

# systemd, pm2, or Docker
pm2 start opalserve -- start
# or
docker run -d --name opalserve -p 3456:3456 ghcr.io/adityaidev/opalserve:latest

Step 5 — Invite Team Members

Generate invite links for your team:

opalserve admin invite alice@company.com --role developer
opalserve admin invite bob@company.com --role developer
opalserve admin invite carol@company.com --role admin

Each command outputs an invite link:

  Invitation created for alice@company.com
  Role: developer
  Link: https://opalserve.company.com/invite/abc123xyz
  Expires: 2026-04-19T00:00:00Z

Share these links with your team members via Slack, email, or however you communicate.

Step 6 — Team Members Connect

Each team member runs these commands on their machine:

# Install OpalServe (if not already installed)
npm install -g opalserve

# Login to the team server
opalserve login https://opalserve.company.com

# Sync the server list and tool index
opalserve sync

The login command will prompt for credentials:

  ? Email: alice@company.com
  ? Password: ********
  Logged in as alice@company.com (developer)
  Team: Acme Engineering

  Syncing... 4 servers, 29 tools available

Alternatively, team members can use an API key:

opalserve login https://opalserve.company.com --api-key osk_abc123

Step 7 — Configure AI Tools

Team members configure their AI tools to connect through OpalServe:

Claude Desktop (claude_desktop_config.json):

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

Claude Code (MCP settings):

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

Now every developer's AI tool has access to all the team's MCP servers through a single connection. The team admin manages everything centrally.

Ongoing Management

Adding new servers

When the admin adds a new server, team members get it on their next sync:

# Admin adds a new server
opalserve server add --name sentry \
  --stdio "npx -y @modelcontextprotocol/server-sentry" \
  --env SENTRY_AUTH_TOKEN=token

# Team members sync to get the new server
opalserve sync

Monitoring usage

Check team usage from the CLI or dashboard:

opalserve admin stats --period 7d

Managing users

# List all users
opalserve admin users

# Change a user's role
opalserve admin permissions --user bob@company.com --role admin

# Set rate limits for a user
opalserve admin limits --user alice@company.com --max-requests 200

Next Steps

• Knowledge Base — upload docs for AI tools to reference
• Admin Dashboard — web UI for monitoring and management
• Integrations — set up GitHub and Slack integrations
• Configuration — full config reference for team mode