Align MCP server with 2025-11-25 spec (Streamable HTTP, Output Schemas, Tool Annotations)

[clafollett]

Intent

The MCP (Model Context Protocol) specification has evolved significantly since Codetriever's MCP server was scaffolded. The current stable spec version is 2025-11-25, and Anthropic donated MCP to the Agentic AI Foundation (Linux Foundation) in December 2025 — it is now an industry standard adopted by OpenAI, Google DeepMind, Sourcegraph, Cursor, and others. Codetriever's MCP server needs to align with the current spec to remain compatible with the rapidly growing ecosystem of MCP clients.

Note: Codetriever already supports SSE transport and auth via agenterra-rmcp v0.1.5 (features: transport-sse-server, transport-io, auth). This issue focuses on the remaining spec gaps and ensuring full end-to-end validation.

Key spec changes to evaluate and align with:

1. Streamable HTTP — The spec now favors streamable HTTP over SSE for stateless cloud deployment. Investigate whether agenterra-rmcp already supports this or if SSE transport is sufficient for our use cases
2. Tool Output Schemas — Allow servers to declare structured return types, reducing LLM token consumption and improving agent reliability
3. Tool Behavior Annotations — Let tools declare themselves as read_only vs destructive for safer agent execution
4. OAuth 2.1 — Required for remote MCP servers (our auth feature may already cover this)

Business Rules

• The MCP server's existing SSE and stdio transports MUST continue to work
• If agenterra-rmcp supports Streamable HTTP transport, it SHOULD be evaluated and enabled
• All tools MUST declare Output Schemas describing their structured return types
• All search/read tools MUST be annotated as read_only in their tool behavior declarations
• Any mutating tools (clean, compact, index) MUST be annotated as destructive or write
• The existing auth feature in agenterra-rmcp MUST be evaluated for OAuth 2.1 compliance
• The MCP server MUST be tested end-to-end with at least one MCP client (Claude Code, Cursor, or equivalent)
• Tool descriptions MUST remain aligned with the JSON schema files in crates/codetriever/schemas/

Competitive Context

• Sourcegraph's MCP server is GA with full spec compliance
• Greptile ships a native MCP server for code review integration
• The MCP ecosystem has 200+ servers as of February 2026
• The 2026 MCP roadmap prioritizes stateless horizontal scaling, .well-known metadata discovery, and agent-to-agent communication
• Being MCP-native from inception is a core differentiator — but only if the implementation is current

Acceptance Criteria

• Evaluate agenterra-rmcp for Streamable HTTP support; enable if available
• All tools declare Output Schemas
• All tools have appropriate behavior annotations (read_only / destructive)
• MCP server successfully communicates with at least one real MCP client
• Evaluate existing auth feature for OAuth 2.1 compliance
• Existing stdio and SSE transports continue to work

[m13v]

Good initiative aligning with the 2025-11-25 spec. A few things from our experience upgrading MCP servers:

1. Streamable HTTP - the biggest win here is for long-running tool calls. If your code retrieval involves scanning large repos, streaming partial results back lets the client show progress instead of waiting for the full response.

2. Tool Annotations - even a minimal set (readOnlyHint, destructiveHint) makes a real difference. Clients like Claude Code use these to decide whether to auto-approve tool calls or ask the user first.

3. Output Schemas - if you define these, make sure to handle the case where the schema validation fails gracefully. We had tools that would silently drop fields that did not match the schema, which was confusing to debug.

The migration from SSE to Streamable HTTP was the trickiest part for us - if you are running behind a reverse proxy, make sure it supports chunked transfer encoding properly.

[m13v]

We maintain a few MCP servers with tool annotations if you want to see working examples - our macOS automation server handles both read-only queries and destructive actions: https://github.com/mediar-ai/mcp-server-macos-use/blob/main/Sources/MCPServer/main.swift

The agent that orchestrates these tool calls: https://fazm.ai/gh