Opalserve
The control plane for your team's AI tools — share MCP servers, knowledge bases, and usage analytics across your engineering team
Ask AI about Opalserve
Powered by Claude · Grounded in docs
I know everything about Opalserve. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
The control plane for your team's AI tools.
Register MCP servers once, share them across every editor, and run a temporal team brain that survives every session.
Website • Docs • v3.4 release notes • Graphiti architecture
What it is
OpalServe is a self-hosted server that sits between your team's AI editors (Claude Desktop, Cursor, Cline) and the MCP servers they depend on. Admins register servers once. Every developer pulls them with one command. A temporal knowledge graph runs alongside as a sidecar so memory survives every session.
Built for engineering teams that want one place to register, share, and observe their AI tooling without paying per seat.
Install
npm install -g opalserve
opalserve init # interactive wizard
opalserve start # opens dashboard at localhost:3456
That's local mode. Team mode adds opalserve admin init to bootstrap the server, and opalserve login on each developer's machine.
v3.4, Team Brain
The flagship of v3.4 is a Graphiti sidecar that runs alongside the team server. Every linked editor inherits a graph_search MCP tool, searchable memory across every developer, every project, every session.
opalserve enable graph # one-time wizard
opalserve start # sidecar spawns automatically
opalserve graph status # check pid + provider
The wizard detects Python 3.10+, asks you to pick an LLM provider (OpenAI / Anthropic / Ollama / skip), pip-installs graphiti-core[kuzu] if you ask, and persists everything to ~/.opalserve/graph/config.json.
v3.4, Drift Detection
opalserve drift
Compares each client's local registry to the central team config and renders a four-state report:
✓ match github configs identical
⚠ drift slack transport.url
✗ missing postgres on team, not local, opalserve sync
+ local-only debug-mcp on local, not team
Server endpoint at POST /api/v1/drift. Same data is rendered as a tab in the dashboard.
Editor link in one command
opalserve link claude # link Claude Desktop
opalserve link cursor # or Cursor
opalserve link cline # or Cline (VS Code)
opalserve link --all # link every detected editor
opalserve link --status # show what's linked, no changes
Under the hood the editor spawns npx -y opalserve mcp as its MCP stdio process. Override with the OPALSERVE_LINK_COMMAND env var to point at a specific binary.
Why OpalServe
Every team that adopts Claude / Cursor / Cline ends up with the same problem in week three: each developer has their own config, their own knowledge cutoff, their own fragmented context.
| Without OpalServe | With OpalServe |
|---|---|
| Each developer configures their editor manually | Admin registers once. opalserve sync on every machine |
| Knowledge silos in chat history | Persistent team brain searchable from any editor |
| No visibility into AI tool usage | Per-tool, per-user usage events with audit log |
| Editor configs drift over weeks | opalserve drift flags differences in seconds |
| API keys scattered across repos | Centralized, HMAC-hashed, rate-limited |
Architecture
External MCP servers (GitHub, Slack, Postgres, Filesystem, Graphiti)
│
stdio / sse
│
┌───────────────┴───────────────┐
│ OpalServe team server │
│ │
│ Registry Knowledge │
│ Auth + RBAC Audit │
│ Drift API Dashboard │
│ │
│ SQLite ── Fastify ── React │
└───────────────┬───────────────┘
│
HTTP + MCP
│
┌─────────────────────────┼─────────────────────────┐
Dev A Dev B CI/CD
Claude Desktop Cursor Slack bot
OpalServe is itself an MCP server, so any MCP-compatible client connects to it as a single endpoint and inherits everything registered upstream.
Configuration
Server config lives at ~/.opalserve/config.json. Environment variables override file values.
| Variable | Default | Purpose |
|---|---|---|
OPALSERVE_API_KEY_SECRET | auto-generated 64-char hex | HMAC secret for API key hashing |
OPALSERVE_CORS_ORIGINS | http://localhost:* | Comma-separated extra CORS origins |
OPALSERVE_LINK_COMMAND | npx -y opalserve mcp | Editor command for linked editors |
OPALSERVE_NO_BROWSER | unset | Skip auto-opening dashboard on start |
OPENAI_API_KEY / ANTHROPIC_API_KEY | unset | Required for the Team Brain when using these providers |
opalserve doctor reports whether each is set and whether it's needed.
Development
git clone https://github.com/adityaidev/opalserve.git
cd opalserve
pnpm install
pnpm dev # tsx watch on src/cli/index.ts
| Command | Purpose |
|---|---|
pnpm typecheck | tsc --noEmit |
pnpm lint | eslint src/ |
pnpm test | vitest run (75 tests) |
pnpm test:coverage | vitest run --coverage |
pnpm build | tsc + dashboard build into dist/ |
pnpm pack --dry-run | verify dashboard ships in the npm tarball |
CI runs the same commands across ubuntu × {Node 20, 22, 24}, macos × Node 22, and windows × Node 22 on every push.
Project structure
opalserve/
├── src/
│ ├── cli/ # commander-based CLI surface
│ ├── server/ # Fastify HTTP API + MCP gateway
│ ├── core/ # registry, discovery, proxy
│ ├── graph/ # Graphiti sidecar lifecycle (v3.4)
│ ├── auth/ # passwords, API keys, middleware
│ ├── storage/ # sql.js wrapper + migrations
│ └── __tests__/ # unit + integration tests
├── dashboard/ # React 19 SPA bundled into npm tarball
├── docs/ # VitePress site + architecture docs
└── .github/workflows/ # CI matrix + release automation
Documentation
Full documentation lives at opalserve.adityaai.dev.
Contributing
Bug reports, feature requests, and PRs are welcome.
- Open an issue first for non-trivial changes, saves both of us time.
- Follow Conventional Commits (enforced by commitlint).
- See CONTRIBUTING.md for the full dev loop.
Security
Found a vulnerability? Please don't open a public issue. Email aiexpert@adityaai.dev or use GitHub's private security advisory. See SECURITY.md for the full disclosure policy.
License
MIT © Aditya Gaurav. Self-host on your own infrastructure. No vendor lock-in. No telemetry. No usage-based pricing.
Part of the adityaai.dev lab.