# MCP Trace Observatory — Full LLM Reference

> Real-time observability monitor for the PlatPhorm agent network: live traces, spans, tool calls, lifecycle states, and system health.

Version: 1.0.0
Upstream: https://trace.platphornews.com

## Data model: Trace
- trace_id (string): unique id
- name, description, ai_summary (string|null)
- agent_name, model_name (string|null)
- status (string): lifecycle status, normalized to one of
  pending | active | running | waiting | partial | completed |
  failed | timed_out | degraded | late | orphaned | cancelled | unknown
- start_time, end_time, created_at (ISO 8601 | null)
- duration_ms, total_spans, total_tool_calls, error_count (number|null)
- source_domain (string|null)

## Endpoints (this app)
GET /api/health
  -> { ok, service, version, uptime_s, upstream: { ok, latency_ms }, timestamp }

GET /api/docs
  -> OpenAPI-style JSON listing of routes, methods, and descriptions.

GET /api/monitor
  -> MonitorSnapshot { ok, fetchedAt, health, stats, metrics[], sources{}, traces[], errors[] }

GET /api/events?since=<ISO>&limit=<n>
  -> { events: [{ id, type, trace_id, status, occurred_at, data }], cursor }
  Event types: trace.started, trace.completed, trace.failed, trace.updated
  n8n-compatible: each event is a flat JSON object safe to map to nodes.

POST /api/webhooks
  Headers:
    X-Signature: sha256=<hex HMAC of raw body using PLATPHORM_WEBHOOK_SECRET>
    X-Idempotency-Key: <client-supplied unique id>
  Body: { type: string, data: object }
  Behavior: signature verified, idempotent (duplicate keys return the first result),
    returns 202 on accept. Retisable/retryable with exponential backoff.

## Auth & limits
- Upstream reads authenticated server-side with PLATPHORM_API_KEY.
- Inbound webhooks authenticated with HMAC-SHA256 over the raw request body.
- Clients never receive secrets; all key usage is server-only.

## Discovery
- https://mind-processing-monitor.platphormnews.com/rss.xml, https://mind-processing-monitor.platphormnews.com/feed.xml
- https://mind-processing-monitor.platphormnews.com/sitemap.xml
- https://mind-processing-monitor.platphormnews.com/llms.txt, https://mind-processing-monitor.platphormnews.com/llms-index.json