Getting Started

This page gets you from nothing to a running OpalServe with at least one MCP server connected and an editor pointed at it. The whole sequence is four commands.

Prerequisites

You need Node.js 20 or newer. Confirm with node --version. OpalServe uses native fetch and crypto.subtle, both of which landed in Node 20.

Install

npm install -g opalserve

Verify:

opalserve --version
# 3.4.0

If you prefer pnpm: pnpm add -g opalserve. If you would rather not install globally, every command works under npx -y opalserve <command>.

Run the wizard

opalserve init

The wizard asks five questions: where to write the config, which mode (local, team-server, team-client), which port, whether to add a starter MCP server, and whether to enable JWT auth on the HTTP API. The defaults are sensible for a single developer, pick local, port 3456, skip auth.

Configuration is written to ~/.opalserve/config.json by default. Override with --config <path>.

Start the server

opalserve start

OpalServe loads config, connects to every registered MCP server, indexes the tools each one exposes, and starts the HTTP API plus the MCP gateway. The dashboard opens at http://127.0.0.1:3456.

You should see something like:

  OpalServe v3.4.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)

Add your first MCP server

If you skipped the starter server in the wizard, add one now. The interactive form 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:

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

Sensitive values are stored in your local config file. They are never sent to the HTTP API and never logged.

Connect your editor

The fastest path is opalserve link:

opalserve link --all

This auto-configures Claude Desktop, Cursor, and Cline to use OpalServe as a single MCP endpoint. To target one editor: opalserve link claude, opalserve link cursor, or opalserve link cline.

Under the hood the editor spawns npx -y opalserve mcp as its MCP stdio process. To override (for example, to point at a specific install path), set OPALSERVE_LINK_COMMAND before running opalserve link.

What's next

Three good next steps depending on what you are after:

• Configuration, every option in ~/.opalserve/config.json, all three operating modes, environment variables.
• Team Brain, turn on the Graphiti sidecar so your AI sessions share memory.
• CLI Reference, every command, every flag, every exit code.