Expose Memory Core healthcheck options in MCP schema

Context

During an external StreamableHTTP deployment verification on 2026-06-18, Memory Core itself was healthy and the embedding-backed raw-memory path worked:

• healthcheck against a mounted /mc/mcp endpoint returned status: healthy in about 1.8s.
• add_memory wrote a labeled probe memory in about 10.2s.
• query_raw_memories for the exact marker returned the probe in about 3.3s with distance: 0 and relevanceScore: 1.

That proves the deployment's write path, embedding provider, Chroma storage, and vector query path were operational. The remaining defect is the MCP tool contract for healthcheck diagnostics.

Release classification: post-release hardening / diagnostics follow-up; not release-blocking.

The Problem

HealthService.healthcheck() already accepts diagnostic options:

• freshObservability
• chromaProbeTimeoutMs
• embeddingWriteCanaryTimeoutMs

Those options are useful for operator probes after a deployment fix, because cached healthy healthcheck payloads can otherwise hide request-fresh fields such as collection counts or canary timing behavior.

However, the MCP healthcheck tool advertises an empty input schema. A live tools/list from the deployed Memory Core returned:

{
  "name": "healthcheck",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

Calling healthcheck with diagnostic args did not fail, but the returned payload reused the old cached timestamp and still reported memoryCount: 0 immediately after a successful probe write. That means the args are not reaching HealthService.healthcheck() through the MCP tool surface.

The Architectural Reality

• ai/services/memory-core/HealthService.mjs has healthcheck({freshObservability = true, chromaProbeTimeoutMs = ..., embeddingWriteCanaryTimeoutMs = ...} = {}).
• ai/mcp/server/memory-core/openapi.yaml declares /healthcheck as a GET operation with no parameters, no JSON request body, and no x-pass-as-object.
• ai/mcp/ToolService.mjs builds argNames only from OpenAPI parameters/request bodies. Without x-pass-as-object, it invokes handlers as handler(...handlerArgs).

So the service-level contract exists, but the MCP contract under-declares it and dispatches the handler with no options.

The Fix

Expose the healthcheck diagnostic options at the MCP contract layer and prove that they are passed into HealthService.healthcheck().

Likely implementation shape:

1. Update ai/mcp/server/memory-core/openapi.yaml so healthcheck has a JSON request body or parameters for:
   • freshObservability boolean
   • chromaProbeTimeoutMs number
   • embeddingWriteCanaryTimeoutMs number
2. Add x-pass-as-object: true if the operation should pass the options object directly.
3. Keep default no-arg healthcheck behavior unchanged.
4. Add focused unit coverage proving:
   • listTools() advertises the options in the healthcheck input schema.
   • callTool('healthcheck', {freshObservability: false}) passes the object to the service handler.
   • timeout budget args are preserved as numbers and reach the handler.

Contract Ledger Matrix

Decision Record impact

none

Acceptance Criteria

• healthcheck tool schema from tools/list exposes the diagnostic options accepted by HealthService.healthcheck().
• healthcheck tool dispatch passes those options through to HealthService.healthcheck().
• No-arg healthcheck remains backward-compatible.
• Focused tests cover schema exposure and dispatch pass-through.
• The PR body includes a short manual verification recipe for a mounted StreamableHTTP deployment.

Out of Scope

• Changing the healthcheck cache policy itself.
• Adding a new expensive census to the default healthcheck payload.
• Fixing any unrelated mounted-path issue in mcpHealthcheck.mjs.
• Changing embedding provider behavior, Chroma collection layout, or query_raw_memories.

Avoided Traps

• Do not add a parallel ad-hoc diagnostic_healthcheck tool while leaving the canonical healthcheck schema stale.
• Do not hardcode deployment-specific timeout values in the OpenAPI schema; defaults belong in ai/mcp/server/memory-core/config.template.mjs / config.mjs.
• Do not mark the service unhealthy merely because an operator requested fresh observability; this ticket is about exposing existing knobs, not changing health semantics.

Related

• #13458
• #13459

Duplicate Sweep

Live latest-open sweep: checked the latest 20 open issues immediately before filing; no equivalent found. Targeted open issue search: checked healthcheck OpenAPI args options MCP Memory Core; no equivalent found. A2A in-flight claim sweep: checked latest 30 all-state messages immediately before filing; no overlapping claim found. Local exact sweep: searched repo issues/discussions/code for freshObservability, chromaProbeTimeoutMs, embeddingWriteCanaryTimeoutMs, and healthcheck schema terms; found the implementation/schema mismatch but no existing ticket.

Origin Session ID: 4ce60429-2986-4543-be2d-741957c75b6c

Handoff Retrieval Hints:

• query_raw_memories("healthcheck freshObservability chromaProbeTimeoutMs embeddingWriteCanaryTimeoutMs openapi.yaml ToolService")
• query_raw_memories("query_raw_memories deployment probe distance 0 relevanceScore 1 healthcheck schema empty")