MCP Tools

In addition to transparently proxying every upstream MCP tool, memtomem-stm provides 12 control tools that inspect and steer the proxy. Four model-facing tools are advertised by default; eight observability tools are opt-in for MCP advertisement.

Advertising observability tools

Eight of the twelve tools are observability tools that are hidden from the MCP tool list by default to free up agent context. Set the env var MEMTOMEM_STM_ADVERTISE_OBSERVABILITY_TOOLS=true in your MCP client config to advertise them — they remain callable from Python tests / direct code paths either way.

Category	Always advertised	Advertised when flag on
Always on	`stm_proxy_select_chunks`, `stm_proxy_read_more`, `stm_surfacing_feedback`, `stm_compression_feedback`	—
Observability	—	`stm_proxy_stats`, `stm_proxy_health`, `stm_proxy_cache_clear`, `stm_surfacing_stats`, `stm_index_stats`, `stm_compression_stats`, `stm_progressive_stats`, `stm_tuning_recommendations`

Proxy stats & control

`stm_proxy_stats`

Token savings, cache hits, per-tool call history.

No parameters. (Observability — advertised only when advertise_observability_tools=true.)

`stm_proxy_health`

Upstream connectivity and circuit breaker state.

No parameters. (Observability.)

`stm_proxy_cache_clear`

Clear the response cache.

Parameter	Type	Required	Description
`server`	string	No	Scope to one upstream server
`tool`	string	No	Scope to one tool

(Observability.)

`stm_proxy_select_chunks`

Pick specific sections from a selective / hybrid TOC returned by an earlier call.

Parameter	Type	Required	Description
`key`	string	Yes	TOC key from the previous response
`sections`	string[]	Yes	Section ids to expand

`stm_proxy_read_more`

Read the next chunk of a progressive response.

Parameter	Type	Required	Description
`key`	string	Yes	Progressive response key
`offset`	integer	Yes	Byte offset to resume from
`limit`	integer	No	Chars to return this turn

Agents should split on the canonical PROGRESSIVE_FOOTER_TOKEN (\n---\n[progressive: chars=) rather than \n---\n alone — the latter collides with Markdown HR / YAML fences.

Surfacing feedback

`stm_surfacing_feedback`

Rate surfaced memories so the auto-tuner can adjust thresholds.

Parameter	Type	Required	Description
`surfacing_id`	string	Yes	Id from the surfacing footer
`rating`	string	Yes	`helpful` / `partially_helpful` / `not_relevant` / `already_known`
`memory_id`	string	No	Specific memory the feedback refers to
`ratings`	object[]	No	Batched per-memory feedback, each with `memory_id` and `rating`

`stm_surfacing_stats`

Aggregated surfacing metrics and feedback distribution. Reports events_total, distinct_tools, total_feedback, per-tool breakdown, rating distribution, helpfulness %, and a configurable recent tail.

Parameter	Type	Required	Description
`tool`	string	No	Filter by upstream tool name
`since`	string	No	ISO-8601 timestamp (e.g. `2026-04-20T00:00:00`) — restricts to events at or after this moment
`limit`	integer	No	Tail size for the `Recent` section (default `10`; `0` hides it)

(Observability.)

Index stats

`stm_index_stats`

STM-driven LTM write statistics for auto-indexing and extraction.

Parameter	Type	Required	Description
`tool`	string	No	Filter by upstream tool name

(Observability.)

Compression feedback

`stm_compression_feedback`

Report missing information that compression dropped.

Parameter	Type	Required	Description
`server`	string	Yes	Upstream server
`tool`	string	Yes	Tool name
`missing`	string	Yes	What the agent needed but didn’t get
`kind`	string	No	Category hint
`trace_id`	string	No	Langfuse trace id if available

`stm_compression_stats`

Compression feedback counts per tool.

Parameter	Type	Required	Description
`tool`	string	No	Filter by tool name

(Observability.)

Progressive delivery stats

`stm_progressive_stats`

Per-response follow-up rate and coverage across all progressive-compressed calls. Each initial chunk and each follow-up stm_proxy_read_more appears as a row in progressive_reads; aggregates collapse per cache key, so a response with five follow-ups is weighted the same as one with none. Reports total reads, total responses, follow-up rate, avg chars served, avg total chars, avg coverage, and a per-tool breakdown.

Parameter	Type	Required	Description
`tool`	string	No	Filter by upstream tool name

(Observability — advertised only when advertise_observability_tools=true.)

INDEX write stats

`stm_index_stats`

STM-driven LTM write activity across both INDEX paths — auto_index_response (verbatim response → markdown chunk) and extract_and_store (response → LLM-extracted facts → markdown chunks). Mirror of stm_surfacing_stats for the write side; INDEX intentionally has no quality signal, so operators only see attempts (per-tool / per-path counts) and 4-label outcomes (stored / error / dedup_skip / extracted_zero_facts).

In the standalone mms server today, Stage 4 INDEX config is valid but inert because no FileIndexer engine is wired at startup. These counters are useful for library integrations and future server wiring, but enabling auto_index in stm_proxy.json does not currently write back to LTM from the standalone server.

Parameter	Type	Required	Description
`tool`	string	No	Filter by upstream tool name — the `__total__` aggregate row is always included

(Observability — advertised only when advertise_observability_tools=true.)

`stm_tuning_recommendations`

Per-tool auto-tuner recommendations derived from recent feedback.

Parameter	Type	Required	Description
`since_hours`	number	No	Time window (default `24.0`)
`tool`	string	No	Filter by tool name

(Observability.)

Proxied upstream tools

Every tool from a registered upstream MCP server is proxied through STM using the pattern {prefix}__{tool}. For example:

mms add filesystem --command npx \
  --args "-y @modelcontextprotocol/server-filesystem ~/projects" \
  --prefix fs
# filesystem's read_file becomes fs__read_file

Proxied tool titles — the annotations.title field rendered by MCP tool-picker UIs (e.g. Claude Code’s /mcp) — are automatically prefixed with [{server}] for attribution: a filesystem server’s Read file tool appears as [filesystem] Read file. This is separate from the {prefix}__{tool} name used when calling the tool, and applies only when the upstream tool provides an annotations.title.

When the agent calls fs__read_file, the proxy runs the active pipeline: CLEAN → COMPRESS → SURFACE, with INDEX available only when an index engine is wired. It returns the compressed response plus any surfaced memories.

See Proactive Surfacing and Compression Strategies for mechanism details.