Cross-application MCP server

CritterWatch ships a Model Context Protocol server (CritterWatch.Mcp) that lets AI agents query and operate the distributed system through the same data plane the SPA reads from. One MCP endpoint covers every monitored Wolverine / Marten / Polecat service — the aggregator is CritterWatch itself.

This page covers the cross-application server. Per-application MCP servers (Marten.Mcp, Polecat.Mcp, WolverineFx.Mcp) ship in their own NuGet packages and expose store / runtime details inside a single service; this page is about the CritterWatch-level surface that spans all of them.

Commercial license required

The entire MCP surface is a paid-tier feature. Every MCP tool is license-gated — including the read/diagnostic tools — so there is no free MCP tier. Without a valid commercial license, every tool returns a "license missing" envelope. (Read-only monitoring through the SPA, by contrast, is always free.)

Looking for "how do I connect"?

If you're on the consumer side — pointing Claude Desktop, MCP Inspector, or a custom MCP agent at a running BFF — see MCP Quick Start for the connection examples, the discovery flow, the deny envelope, and tenant-scoped invocations. This page is the server-side reference.

What's mounted

The BFF mounts the MCP server at /api/mcp (the CritterWatchMcpExtensions.DefaultRoute constant). Clients connect over streamable HTTP; no SSE fallback is required.

POST http://your-critterwatch-host/api/mcp

For multi-package composition (CritterWatch tools alongside per-store tools), see Composition below.

Tool catalog

Read tools (21)

Always license-gated. RBAC-free except the dead-letter reads, which are gated on mcp.dlq.read — see below.

Family	Tools	Capability
Alerts	list_active_alerts, get_alert, summarize_active_alerts	—
Health	summarize_cluster_health, get_service_health, list_degraded_surfaces	—
Performance	get_backlog_state, list_backlog_hotspots, get_projection_lag	—
OpenTelemetry traces	query_recent_traces, get_trace, check_trace_provider_health	—
Message routing	get_message_routing, list_message_routing, explain_message_routing	—
Document explorer	list_document_types, query_documents, get_document	—
Lifecycle	describe_lifecycle	—
Dead letters	summarize_dead_letters, query_dead_letters	mcp.dlq.read

Dead-letter reads

summarize_dead_letters gives grouped counts by message type and exception type — the triage view. query_dead_letters returns individual envelopes including their ids, which are exactly what replay_dead_letters / discard_dead_letters take. Together they close the investigate → explain → replay loop that the action tools alone could not: before these existed an agent had no way to discover an envelope id short of a human pasting it out of the console.

They carry a capability where the other read tools do not, because dead letters contain message bodies and exception detail — business data. "May look at them" is worth granting separately from "may act on them".

Always check databasesAnswered against databasesAnnounced

Both tools fan out across every physical message database a service owns, and both report how many were asked versus how many replied, plus a partial flag and a warning string.

A store that fails to answer is otherwise indistinguishable from a store with no rows. That is exactly how the console came to assert "No dead letter queue entries found." over a queue holding 42 dead letters on an eight-database deployment (#915). An empty result with partial: true means some stores did not report — not that the queue is empty. Do not conclude a service is clean on the strength of a partial read.

Trace tools route through the per-service ITraceProvider binding cascade — operators bind Jaeger, Datadog, etc. to specific services and the tools surface whichever provider is configured for the service in the query.

Action tools (27, RBAC-gated)

Each takes a target serviceName (or resource id) and runs the RBAC enforcement pipeline before publishing the existing Wolverine command. On allow, returns an Accepted JSON envelope; on deny, returns a Forbidden / LicenseMissing envelope.

Family	Tools	Capability
DLQ	replay_dead_letters, discard_dead_letters	dlq.replay, dlq.discard
Projection	pause_projection, restart_projection, rebuild_projection, eject_projection	projection.pause, projection.restart, projection.rebuild, projection.eject
Tenant	add_tenant, enable_tenant, disable_tenant, remove_tenant, hard_delete_tenant	tenant.add, tenant.enable, tenant.disable, tenant.remove, tenant.hard-delete
Alert	acknowledge_alert, snooze_alert, clear_alert	alert.acknowledge, alert.snooze, alert.clear
ChaosMonkey	enable_chaos_monkey, disable_chaos_monkey, set_chaos_monkey_failure_rate, set_chaos_monkey_slow_handler, set_chaos_monkey_projection_failure_rate, set_chaos_monkey_projection_poison, clear_chaos_monkey_projection_poison, seed_dead_letters	chaos-monkey.toggle (on/off), chaos-monkey.configure (rate / delay / poison / seeding)
Listener	pause_listener, restart_listener, drain_listener	listener.pause, listener.restart, listener.drain
Metrics	delete_metrics_samples	metrics.delete
Service	evict_service	service.evict

ChaosMonkey and Tenant deliberately split their capabilities so an operator trusted to stop chaos isn't automatically trusted to crank it higher, and a tenant cleanup grant doesn't extend to dropping the tenant's database. See the RBAC page for the full rationale.

Deterministic chaos: prefer it over the rates

Three of the ChaosMonkey tools produce a known failure rather than a probable one. Reach for them whenever you need to reason about a specific failure — which is most of the time.

Tool	Use instead of	Why
set_chaos_monkey_projection_poison	set_chaos_monkey_projection_failure_rate	The rate is a dice roll per apply, so the alert, the dead-letter drill-in and the projection stepper each land on a different random event. A poison names one event — by type, or by stream and version — so all three agree, and the stepper reproduces it on the exact step instead of failing randomly under itself. It fires independently of the rate, so you can reproduce with the rate at 0.
seed_dead_letters	waiting on set_chaos_monkey_failure_rate	The failure rate has produced Handled=905, DeadLetter=0 after minutes on a service whose handlers mostly succeed. Seeding writes a known number immediately, with varied message types, exception types, attempt counts and ages so the DLQ summary groups meaningfully.
clear_chaos_monkey_projection_poison	—	Disarms the poison and leaves the probabilistic rate alone. Use disable_chaos_monkey to stop everything.

Seeded dead letters are replayable: a configurable fraction is seeded recoverable and succeeds on replay, while the rest throw again and return to the queue. That makes "replay the recoverable ones, discard the rest" a real decision rather than a scripted gesture where everything replays cleanly.

Both write to real storage on a real service. They are chaos-monkey.configure-gated and license-gated, like the rest of the family — use them against staging and dev services.

Per-tenant scoping on projection action tools

pause_projection, restart_projection, and rebuild_projection accept an optional tenantId argument. When supplied, the action runs against only that tenant's projection shard (using the same per-tenant daemon path the SPA's per-tenant Rebuild button uses). When omitted on a multi-tenant service, the action targets the store-global shard — typically what you want on a single-tenant service and almost never what you want when tenants are partitioned.

For authorizers, the RBAC resource scope shifts from serviceName to {serviceName}:{tenantId} when the agent supplies a tenant id. That lets you write per-tenant grants without overloading service-level ones:

public Task<bool> IsAllowedAsync(
    ClaimsPrincipal principal, string capability, string? resource, CancellationToken ct)
{
    if (capability == Capabilities.ProjectionRebuild
        && resource is { } scope && scope.Contains(':'))
    {
        var (service, tenantId) = SplitScope(scope);
        return Task.FromResult(principal.HasGrant(service, tenantId, capability));
    }

    // … other paths
    return Task.FromResult(false);
}

This is the same scope shape used by the SignalR-routed commands and the per-tenant HTTP API calls — one resource convention across the three surfaces.

RBAC enforcement

Each action tool calls a single helper before publishing:

var gate = await McpAuthorizationContext.EnforceAsync(
    httpContextAccessor, authorizer,
    Capabilities.DlqReplay, resource: serviceName, ct);
if (gate.IsDenied) return gate.DenyPayload!;

The helper runs the license guard + RBAC check (RbacGuard.IsAllowedAsync against HttpContext.User). Deny produces a stable-shape JSON envelope:

Field	Meaning
error	"LicenseMissing" or "Forbidden"
message	Human-readable explanation
capability	The capability string the caller is missing (only on Forbidden)
resource	The resource scope the deny was evaluated against (only on Forbidden, only when supplied)

Off-mode hosts (no custom authorizer registered) see the DefaultAllowAuthorizer and every grant succeeds — same shape as the HTTP enforcement layer. See RBAC for the operator- facing detail.

Why stateless transport

The MCP server runs with HttpServerTransportOptions.Stateless = true. This is required for RBAC enforcement: in the default (stateful) mode the HttpContext reachable via IHttpContextAccessor is the one that initialised the MCP session, not the one of the current tool invocation. HttpContext.User would be stale (or empty) for every action after init.

Stateless mode also removes the need for session affinity on multi-node deployments — a useful side benefit for clustered CritterWatch installations.

Licensing

All MCP tools are license-gated. Read tools and action tools both check McpLicenseGuard.IsAllowed() before doing any work; the first check caches the result for the process lifetime. The license is the same JASPERFX-signed license CritterWatch's core uses (see Licensing).

In tests, pre-seed the cache via CritterWatch.Mcp.Licensing.McpLicenseGuard.SetForTesting(true) at assembly load — see src/McpTests/LicenseSetup.cs for the module- initialiser pattern.

Composition

Standalone (default)

builder.Services.AddCritterWatchMcp();
// …
app.MapCritterWatchMcp();

This:

• Registers an MCP server with the streamable-HTTP transport configured stateless.
• Adds all 48 tools across the read + action families.
• Wires AddHttpContextAccessor() so action tools can resolve the caller's principal.

Chained alongside per-store servers

If your host already composes an MCP server (e.g. with Marten.Mcp + WolverineFx.Mcp), chain CritterWatch's tools onto the existing builder:

builder.Services
    .AddMcpServer()
    .WithHttpTransport(o => o.Stateless = true)
    .AddCritterWatchMcp()
    .AddMartenMcp()
    .AddWolverineMcp();

When composing, the host is responsible for setting Stateless = true on the transport and for registering AddHttpContextAccessor() itself. The IMcpServerBuilder overload of AddCritterWatchMcp() only chains the tools; the standalone IServiceCollection overload sets up both for you.

Connecting an MCP client

Any client that speaks streamable HTTP MCP can connect — for example the @modelcontextprotocol/inspector:

npx @modelcontextprotocol/inspector
# URL: http://localhost:5173/api/mcp (or your BFF's address)

For Claude Desktop or similar, configure the MCP server in the client's config to point at /api/mcp on your CritterWatch host. The transport is streamable HTTP, not stdio — pick the matching client setting.

If your host has RBAC enforcement on, the MCP client needs to present an authenticated principal that the host's authentication layer recognises (OIDC bearer token, signed header from a reverse proxy, etc.). Anonymous calls hit the fail-closed-on-no-principal branch and get a Forbidden envelope.

Testing

McpTests in the CritterWatch repo covers every tool with the same matrix: happy-path publish, RBAC deny, fail-closed-on-no-principal, license-missing, plus per-tool bad-request cases. Tools are invoked directly with substituted IHttpContextAccessor / authorizer / IMessageBus — no MCP server stand-up needed for unit-style tests. See src/McpTests/Mcp/DlqActionToolsTests.cs for the reference shape.

Related

• RBAC — capability catalog + authorizer interface
  • custom authorizer skeleton
• Licensing — the same license gates both surfaces