Getting Started

Get OpalServe up and running in under five minutes. This guide walks you through installation, initial configuration, adding your first MCP server, and verifying everything works.

Prerequisites

Before installing OpalServe, make sure you have:

Requirement	Minimum Version	Check Command
Node.js	20.0.0	node --version
npm	9.0.0	npm --version

Why Node.js 20+?

OpalServe uses native fetch, crypto.subtle, and other modern APIs that landed in Node.js 20. Earlier versions will not work.

You will also need at least one MCP server to connect to. If you do not have one yet, the setup wizard can configure the filesystem server for you automatically.

Step 1 — Install OpalServe

npm install -g opalserve

Verify the installation:

opalserve --version
# 3.0.0

Alternative installation methods

pnpm:

pnpm add -g opalserve

Run without installing (npx):

npx opalserve init

As a project dependency:

npm install opalserve

See the Installation guide for all options, including running from source.

Step 2 — Run the Setup Wizard

opalserve init

The interactive wizard will ask you:

1. Configuration location — Where to store your config file (default: ~/.opalserve/config.json)
2. Mode — local (single developer), team-server (host for your team), or team-client (connect to a team server)
3. HTTP API port — Port for the REST API and dashboard (default: 3456)
4. First MCP server — Optionally register a server right away (filesystem, GitHub, or skip)
5. Authentication — Enable JWT auth for the HTTP API (recommended for team mode)

After the wizard completes, you will see:

  Configuration written to ~/.opalserve/config.json

  Next steps:
    opalserve start         Start the registry
    opalserve server add    Add more MCP servers
    opalserve --help        See all commands

Step 3 — Start the Registry

opalserve start

OpalServe will:

• Load your configuration
• Connect to all registered MCP servers
• Discover and index their tools
• Start the HTTP API and MCP gateway
• Display a summary of available tools

  OpalServe v3.0.0

  Connecting to 1 server(s)...

  files       connected   (12 tools)

  HTTP API     http://127.0.0.1:3456
  MCP Gateway  stdio ready
  Dashboard    http://127.0.0.1:3456/dashboard

  12 tools available across 1 server(s)

Step 4 — Add Your First MCP Server

If you skipped the server setup in the wizard, add one now:

# Interactive mode — walks you through it
opalserve server add

# Or use a one-liner for the filesystem server
opalserve server add \
  --name my-files \
  --stdio "npx -y @modelcontextprotocol/server-filesystem /path/to/your/project"

For GitHub integration:

opalserve server add \
  --name github \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_your_token_here

Environment variables

Sensitive values like API tokens are stored in your local config file. They are never sent to OpalServe's HTTP API or exposed in logs.

Step 5 — Search and Discover Tools

Once servers are connected, you can search across all of them:

# List every tool from every server
opalserve tools list

# Full-text search
opalserve tools search "read file"

# Filter by server
opalserve tools list --server github

Example output:

  Search results for "read file" (3 matches)

  my-files:read_file          Read the contents of a file
  my-files:read_multiple_files Read several files at once
  github:get_file_contents     Get contents of a file from a repository

Step 6 — Connect Your AI Tool

Point your MCP client at OpalServe instead of configuring individual servers.

Claude Desktop — add to claude_desktop_config.json:

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

Claude Code — add to your MCP settings:

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

Cursor — add to your MCP configuration in Cursor settings with the same format as above.

Now your AI tool has access to every server registered in OpalServe through a single connection.

What's Next

You are up and running. Here is where to go from here:

• Team Setup — Configure OpalServe for your engineering team with shared servers and centralized management
• Configuration Reference — All config options for local, team-server, and team-client modes
• CLI Reference — Every command, flag, and option
• Popular MCP Servers — Curated list of servers to connect
• HTTP API — REST API reference for building integrations
• Admin Dashboard — Web UI for monitoring and management