MCP Tool Server + Live Agent Observability Dashboard

A small, production-shaped MVP for demonstrating MCP tool use with real persistence and live tracing.

What is here

• MCP server — Node/TypeScript using the official @modelcontextprotocol/server SDK.

• 4 tools — createTask, queryTasks, updateTask, checkServerHealth.

• MongoDB — task and trace collections with indexes.

• Observability API — Express API that reads trace history and accepts trace events from the MCP process.

• Socket.io — every completed tool call is pushed to connected dashboards immediately.

• React dashboard — deliberately plain: trace list, filters, timing/status badges, and JSON detail panels.

• Tests — Vitest tests for task behavior, tracing, HTTP endpoints, and the React shell.

• Claude wiring — example configuration for Claude Desktop and Claude Code.

Related MCP server: OTEL MCP Server

Runtime shape

Claude Desktop / Claude Code
          |
          | MCP over stdio
          v
  +-------------------+
  |   MCP server      |
  | 4 real tool calls |
  +---------+---------+
            |
       MongoDB task + trace writes
            |
            +----------------------+
            |                      |
            v                      v
  +-------------------+    +-------------------+
  | Observability API | -> | Socket.io clients |
  +-------------------+    +-------------------+
            ^
            |
      React dashboard

The dashboard does not sit in the MCP protocol path. If the dashboard is down, the MCP process can still save the trace to MongoDB. When the dashboard comes back, it reads the persisted trace history. The HTTP notification exists only to make the UI feel live.

Prerequisites

Node.js 20+ is required for the current MCP TypeScript SDK. MongoDB can be local, Atlas, or the included Docker service.

cp .env.example .env
npm install
docker compose up -d mongo

The current MCP TypeScript SDK v2 is the stable line and uses McpServer with registerTool; stdio is the local host transport. See the official SDK docs for the current API.

Run the apps

Terminal 1 — observability API:

npm run dev -w @mcp-observability/observability

Terminal 2 — React dashboard:

npm run dev -w @mcp-observability/dashboard

The dashboard will be at http://localhost:5173 and the observability API at http://localhost:4000.

Terminal 3 — optional standalone MCP process for Inspector:

npm run inspect:mcp

Claude Desktop

Build the MCP server once:

npm run build -w @mcp-observability/core
npm run build -w @mcp-observability/mcp-server

Copy the example in config/claude_desktop.example.json into your Claude Desktop MCP config and replace the absolute path with the path to this repository. Keep OBSERVABILITY_URL pointing at the running observability API.

The MCP process writes protocol traffic to stdout and diagnostics to stderr. Do not add ordinary console.log calls to the MCP process.

Claude Code

Use config/claude_code.example.json as the shape for a project-level .mcp.json. The command can point to the built dist/index.js or use npx tsx during development.

Live demo

1. Start MongoDB.

2. Start the observability API.

3. Start the React dashboard.

4. Launch Claude Desktop or Claude Code with this MCP server configured.

5. Ask: Create a high priority task called fix login bug.

6. Ask: List the open tasks.

7. Ask: Mark the fix login bug task as in_progress.

8. Ask: Is the task server healthy?

9. Keep the dashboard visible. Each tool call appears as a trace, including arguments, status, duration, and result.

Tool contract

createTask

Creates a task in tasks.

{
  "title": "fix login bug",
  "priority": "high"
}

queryTasks

Lists tasks with optional text, status, and priority filters.

{
  "text": "login",
  "status": "open",
  "limit": 25
}

updateTask

Changes a task's title, priority, or status.

{
  "taskId": "...",
  "status": "in_progress"
}

checkServerHealth

Pings MongoDB and returns service health plus latency.

Testing

npm test
npm run typecheck
npm run build

The tests deliberately keep the database boundary injectable so most behavior can run without a real MongoDB instance. For a real integration environment, point MONGODB_URI at a dedicated test database and add a Mongo-backed test stage in CI.

Tradeoffs / next production steps

This is an MVP, not a hosted multi-tenant tracing product. The important boundary is already there: MCP tool execution is instrumented, traces are durable, and the UI consumes a simple event stream. A production system would add authentication, redaction policy, trace correlation across model turns, retention jobs, sampling, rate limiting, pagination cursors, and multi-instance event delivery.