ensemble-mcp docs
Presentation GitHub

Web Dashboard

ensemble-mcp includes a local web dashboard for browsing patterns, sessions, drift history, indexed projects, skills, and server settings.

Starting the Dashboard

# Default: port 8787, auto-opens browser
ensemble-mcp web

# Custom port
ensemble-mcp web --port 9000

# Don't auto-open browser
ensemble-mcp web --no-open

# Specify reports directory
ensemble-mcp web --reports-dir ./reports

The dashboard binds to 127.0.0.1 only — it is accessible only from your local machine. No authentication is required.

Dashboard URL

http://127.0.0.1:8787

The startup output shows the URL, database path, and version:

  ensemble-mcp dashboard v0.1.0b4
  URL: http://127.0.0.1:8787
  Database: ~/.cache/ensemble-mcp/data.db
  Press Ctrl+C to stop

Architecture

The dashboard is built with:

The dashboard opens its own SQLite connections (separate from the MCP server) to avoid blocking. Read endpoints use PRAGMA query_only = ON for safety.

Dashboard Pages

Summary

The landing page shows aggregate statistics:

Patterns

Browse, search, edit, and delete stored patterns:

Skills

View skill suggestions and tracked skill usage:

Projects

Browse indexed projects:

Drift

Drift check history:

Sessions

Pipeline session checkpoints:

Settings

View and edit server configuration:

Health

Server health information:

JSON API Endpoints

The dashboard exposes a REST API under /api/. All responses use the standard envelope format:

{
  "ok": true,
  "data": { ... },
  "error": null,
  "meta": {
    "duration_ms": 5,
    "source": "dashboard",
    "confidence": "exact"
  }
}

Read Endpoints

MethodPathDescription
GET/api/summaryAggregate counts and recent activity
GET/api/patternsPaginated pattern list (?limit=&offset=&project=)
GET/api/patterns/{id}Single pattern detail
GET/api/skillsSkill suggestions and tracked skills
GET/api/skills/staleSkills not matched within threshold
GET/api/projectsIndexed projects with file counts
GET/api/projects/{path}Project detail (languages, roles, exports)
GET/api/projects/{path}/healthIndex staleness and missing files
GET/api/driftDrift check history (?project=&from=&to=&limit=)
GET/api/sessionsPaginated session list
GET/api/sessions/{id}Session detail with full state
GET/api/healthServer health and counts
GET/api/settingsCurrent config with source map
GET/api/settings/schemaField names, types, defaults for the settings form

Mutation Endpoints

MethodPathDescription
DELETE/api/patterns/{id}Delete a pattern
PUT/api/patterns/{id}Edit pattern fields
POST/api/patterns/prunePrune stale patterns
POST/api/skills/suggestions/{id}/actionAccept/dismiss/defer a suggestion
DELETE/api/skills/tracked/{id}Remove a tracked skill
PUT/api/settingsUpdate global config
POST/api/resetReset all data ({"confirm": true} required)
POST/api/projects/{path}/reindexForce re-index a project
DELETE/api/projects/{path}Delete a project's index

Report Endpoints

MethodPathDescription
GET/api/reports/markdownBug Hunter report in markdown
GET/api/reports/historyReport history
GET/api/reports/summaryReport summary

Port Conflicts

If port 8787 is already in use, the dashboard exits with a suggestion:

Error: Port 8787 is already in use.
Try: ensemble-mcp web --port 8788

Database Independence

The dashboard creates its own SQLite connections, so it can run independently from the MCP server. It also calls ensure_schema() at startup, so the dashboard works even if the MCP server has never run.

Next Steps