Epic: feat(mcp): adopt the full client-supported MCP spec surface - make madtea the best-behaved MCP citizen there is #412

New issue

Open

opened 2026-08-17 15:47:29 +00:00 by hexajon · 0 comments

hexajon commented

2026-08-17 15:47:29 +00:00

Owner

Goal

madtea's MCP server currently ships tools with a bare Name plus Description, and it leaves most of the MCP spec's UX surface unused. I want to adopt every spec feature that clients demonstrably support, so madtea is maximally discoverable, self-describing, safe and pleasant in Claude Code, and correct for Codex and Gemini CLI.

Verified client-support matrix (Claude Code v2.1.201, 2026-07-06)

Sources: the official docs (code.claude.com/docs/en/mcp, /en/permissions), CLI bundle inspection, and MCP spec 2025-11-25.

Feature	Claude Code support	madtea today
`annotations.title` on tools	CONFIRMED - replaces the wire name in the tool-call display line (`annotations?.title \|\| name`)	0 of ~36 tools
Behavior hints (readOnlyHint/destructiveHint/idempotentHint/openWorldHint)	Parsed into schemas; NO documented permission or UX effect	none
Elicitation (`elicitation/create`)	CONFIRMED - "Claude Code displays an interactive dialog... No configuration is required"	none
Progress notifications	CONFIRMED functional - resets the 5-min idle timeout on long tool calls (it does not extend the hard per-server timeout)	1 call (tools_workflow.go:58)
`outputSchema`	Accepted; passed through to the model, no differential rendering	structuredContent returned in ~18 places, no declared schemas
`_meta["anthropic/maxResultSizeChars"]`	CONFIRMED - per-tool large-output budget, independent of MAX_MCP_OUTPUT_TOKENS	none
`_meta["anthropic/requiresUserInteraction"]`	CONFIRMED (v2.1.199+) - always prompts, even in bypassPermissions	none
`list_changed` (tools/prompts/resources)	CONFIRMED - "Claude Code automatically refreshes the available capabilities"	unverified for madt_enable's gated domains
Prompts	CONFIRMED - surface as slash commands `/mcp__<server>__<promptname> [args]`	4 prompts
Resources	CONFIRMED - @-mentionable (`@server:protocol://path`), fuzzy-searchable, auto-attached	18 registrations, audience/priority annotations
Completions	Spec-supported; no evidence Claude Code uses them for autocomplete	4 uses (already implemented)
Icons (tools/resources/prompts/implementations)	In spec; rendering in Claude Code UNCONFIRMED	none

Consciously deferred (not sub-issues)

Sampling (sampling/createMessage): madtea has no use case, because the caller already is the LLM, and client support is unconfirmed. Revisit if a server-side reasoning need appears.
Logging notifications: a debug channel only in Claude Code, with no user-facing rendering found. Not worth the server plumbing now.
Completions: already implemented for prompt and resource arguments. Nothing further until a client demonstrably consumes them.

Exit criterion

Every sub-issue closed. A parity-style test enforces that a new tool cannot be registered without a title and hints. Reference docs regenerated. Verified live in a Claude Code session: display names, the elicitation dialog, slash-command prompts, and @-mention resources.

Why: I want madtea to use 100% of the MCP spec surface that clients actually support. Note: the earlier display-name emoji work overlaps the icons and title surface.

## Goal madtea's MCP server currently ships tools with a bare `Name` plus `Description`, and it leaves most of the MCP spec's UX surface unused. I want to adopt every spec feature that clients demonstrably support, so madtea is maximally discoverable, self-describing, safe and pleasant in Claude Code, and correct for Codex and Gemini CLI. ## Verified client-support matrix (Claude Code v2.1.201, 2026-07-06) Sources: the official docs (code.claude.com/docs/en/mcp, /en/permissions), CLI bundle inspection, and MCP spec 2025-11-25. | Feature | Claude Code support | madtea today | |---|---|---| | `annotations.title` on tools | CONFIRMED - replaces the wire name in the tool-call display line (`annotations?.title \|\| name`) | 0 of ~36 tools | | Behavior hints (readOnlyHint/destructiveHint/idempotentHint/openWorldHint) | Parsed into schemas; NO documented permission or UX effect | none | | Elicitation (`elicitation/create`) | CONFIRMED - "Claude Code displays an interactive dialog... No configuration is required" | none | | Progress notifications | CONFIRMED functional - resets the 5-min idle timeout on long tool calls (it does not extend the hard per-server timeout) | 1 call (tools_workflow.go:58) | | `outputSchema` | Accepted; passed through to the model, no differential rendering | structuredContent returned in ~18 places, no declared schemas | | `_meta["anthropic/maxResultSizeChars"]` | CONFIRMED - per-tool large-output budget, independent of MAX_MCP_OUTPUT_TOKENS | none | | `_meta["anthropic/requiresUserInteraction"]` | CONFIRMED (v2.1.199+) - always prompts, even in bypassPermissions | none | | `list_changed` (tools/prompts/resources) | CONFIRMED - "Claude Code automatically refreshes the available capabilities" | unverified for madt_enable's gated domains | | Prompts | CONFIRMED - surface as slash commands `/mcp__<server>__<promptname> [args]` | 4 prompts | | Resources | CONFIRMED - @-mentionable (`@server:protocol://path`), fuzzy-searchable, auto-attached | 18 registrations, audience/priority annotations | | Completions | Spec-supported; no evidence Claude Code uses them for autocomplete | 4 uses (already implemented) | | Icons (tools/resources/prompts/implementations) | In spec; rendering in Claude Code UNCONFIRMED | none | ## Consciously deferred (not sub-issues) - **Sampling** (`sampling/createMessage`): madtea has no use case, because the caller already is the LLM, and client support is unconfirmed. Revisit if a server-side reasoning need appears. - **Logging notifications**: a debug channel only in Claude Code, with no user-facing rendering found. Not worth the server plumbing now. - **Completions**: already implemented for prompt and resource arguments. Nothing further until a client demonstrably consumes them. ## Exit criterion Every sub-issue closed. A parity-style test enforces that a new tool cannot be registered without a title and hints. Reference docs regenerated. Verified live in a Claude Code session: display names, the elicitation dialog, slash-command prompts, and @-mention resources. Why: I want madtea to use 100% of the MCP spec surface that clients actually support. Note: the earlier display-name emoji work overlaps the icons and title surface.  - [ ] #6 - [ ] #7 - [ ] #8 - [ ] #411

hexajon added the

epic

label

2026-08-17 15:47:29 +00:00

hexajon referenced this issue

2026-08-17 15:57:35 +00:00

feat(mcp): icons on server, tools, prompts, and resources - verify client rendering first #411

hexajon referenced this issue

2026-08-17 15:59:04 +00:00

mcp: aim at the draft spec #414

hexajon referenced this issue

2026-09-08 20:38:23 +00:00