Vigil

Observability and awareness infrastructure for AI agents.

Vigil is two layers in one package:

• MCPWatch — the silent-failure watchdog for MCP servers. One-line instrumentation for any Python MCP server (FastMCP and low-level `mcp.server.lowlevel.Server`). Gateways and dashboards already give you latency and error charts. The thing nobody catches is the call that *looks* successful but returns nothing: empty, null, or blank content with no error raised. MCPWatch flags those as a distinct `silent` status, on top of per-tool latency (p50/p95/p99), error rates, and `isError` responses. Used in production across 95+ MCP tools.
• Awareness platform — daemon-compiled context, signal protocol, session handoff, frame-based tool filtering, MCP server. The nervous system layer most agent frameworks skip.

Most agent memory tools are filing cabinets. Vigil is a stethoscope and a nervous system.

The Problem

MCP servers fail silently. A tool returns empty content, the SDK swallows the exception, the agent treats it as "no results found" and you find out three days later from a customer ticket. Latency and error monitoring is now table stakes (gateways, OpenTelemetry, and FastMCP itself emit it). But none of them flag the empty-but-not-errored response — the failure mode your agent quietly hallucinates around. That gap is what MCPWatch exists to close.

Agents forget everything between sessions. They load all tools regardless of context (wasting 50K+ tokens). They can't coordinate across sessions or hand off work to each other. Every conversation starts cold.

What Vigil Does

MCPWatch — the MCP silent-failure watchdog — One line wraps any Python MCP server (FastMCP or low-level `mcp.server.lowlevel.Server`). Its headline job: detect silent failures — calls that return empty, null, or blank content with no error raised — and record them as a distinct `silent` status that shows up in health, per-tool stats, and alerts. It also tracks tool-call latency (p50/p95/p99), per-tool error rates, `isError` responses, and call volume over time. REST API, CLI, and alert hooks. MIT, no config required.

MCP Production Observability

Monitor any MCP server with one line of code. Tracks tool calls, latency, errors, and emits alerts automatically.

from mcp.server.fastmcp import FastMCP
from vigil.mcpwatch import instrument

mcp = FastMCP("my-server")

@mcp.tool()
async def search(query: str) -> str:
    return "results"

# One line — all tools are now monitored
watch = instrument(mcp)

What it monitors:

• Silent failures — calls that return empty, null, or blank content with no error raised. Recorded as a distinct `silent` status, surfaced in health and stats, and alerted on. This is the headline feature.
• Every tool call: name, duration, success / error / silent
• Latency spikes (configurable threshold, default 5s)
• Error patterns with full tracebacks (including low-level `isError` responses)
• Server silence (no calls at all for N minutes)

Three ways to use it:

# 1. Local Vigil — store in same DB as your signals
watch = instrument(mcp, db_path="vigil.db")

# 2. Vigil Cloud — send to your hosted instance
watch = instrument(mcp, api_key="vgl_...")

# 3. Memory-only — just in-process stats
watch = instrument(mcp)

Check health anytime:

health = watch.health()
# {'server': 'my-server', 'status': 'degraded', 'total_calls': 1247,
#  'total_errors': 25, 'error_rate': 0.02,
#  'total_silent': 140, 'silent_rate': 0.112,   # <- the failures nobody else flags
#  'tools': {'search': {'avg_ms': 42, 'p95_ms': 180, 'silent_count': 140}}}

watch.recent_silent()   # the actual empty/null calls, per tool

A tool that returns `""`, `None`, or `[]` with no exception is the classic MCP

blind spot — the SDK reports success, your agent improvises around the void.

MCPWatch turns that into a first-class signal.

CLI:

vigil mcp-health              # All monitored servers
vigil mcp-health -s my-server # Specific server

REST API (6 endpoints):

Why Not Just Use Mem0/Letta/LangGraph?

Vigil is the nervous system. Others are the filing cabinet. Use them together — Vigil handles awareness and coordination, Mem0/Letta handles deep memory.

License

MIT