MCP compatibility register

This is the living architectural compatibility register for the Blurt MCP server and the upstream Model Context Protocol (MCP) specification.

It is not a one-time audit and it is not a checklist for implementing every optional MCP feature. Its purpose is governance: every meaningful compatibility decision should be explicit, easy to review and revisited when the specification, SDK or product direction changes.

Principle

The goal is not maximum MCP feature coverage. The goal is clear compatibility ownership.

A missing optional feature is acceptable when it is intentional and documented. An undocumented protocol, transport or capability difference is not acceptable.

Review this document whenever:

• the MCP specification changes;
• @modelcontextprotocol/sdk is upgraded;
• this server adds or removes MCP capabilities, transports, tools, resources, signing modes or authentication;
• public documentation claims support for a specific MCP specification version.

Current baseline

Item	Current value
Last reviewed against MCP spec	2025-06-18
Upstream spec source	https://modelcontextprotocol.io/specification/2025-06-18
MCP SDK package	@modelcontextprotocol/sdk
SDK version at review	1.29.0
SDK latest protocol version at review	2025-11-25
SDK supported versions at review	2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07
Project transports	stdio; stateless Streamable HTTP POST /mcp
Project capabilities	tools; resource templates
Project non-goal	full MCP feature coverage

Status meanings

Status	Meaning
Implemented	Project code intentionally implements the relevant behavior.
Implemented by SDK	The behavior is inherited from the MCP TypeScript SDK and currently needs no project code.
Intentional divergence	The project deliberately differs from a strict or common reading of the spec and documents why.
Stateless compatibility mode	The behavior follows from the public stateless HTTP design and limits stricter transport claims.
Optional deferred	Valid optional MCP feature, deferred until it provides project value.
Out of scope	Not part of this server's product role unless product direction changes.
Monitor	Accepted current behavior that should be rechecked on SDK/spec/product changes.

Priority meanings

Priority	Meaning
Now	Should be fixed before making stronger MCP-version or transport-conformance claims. Usually a mandatory spec/security requirement or a low-cost correction.
Next	Should be addressed in the next protocol/transport hardening pass, but does not block current public documentation if accurately disclosed.
Later	Valid optional feature or polish; implement only when it provides project value.
Won't implement	Deliberately out of scope for this project unless the product direction changes.
Monitor	Inherited SDK behavior or spec/SDK drift that should be rechecked on upgrades.

Implementation scope statement

The precise public wording for the current state is:

This server uses the Model Context Protocol TypeScript SDK and supports MCP clients negotiating protocol version 2025-06-18 for its implemented tools and resource-template features.

Do not claim full MCP conformance, certification or complete Streamable HTTP support unless every material item in this register has been resolved or explicitly accepted for that stronger claim.

Register

Streamable HTTP security

• Status: Intentional divergence
• Priority: Monitor
• Spec point: Servers implementing Streamable HTTP MUST validate the Origin header to mitigate DNS rebinding.
• Current behavior: The public HTTP endpoint does not maintain a client Origin allow-list. Requests with Origin are treated as non-authoritative and accepted by the public endpoint.
• Decision: Keep the public endpoint no-ambient-authority; do not add an AI-product Origin registry.
• Why: An Origin allow-list is not maintainable for an open public MCP endpoint and would turn client compatibility into operator-maintained policy. DNS rebinding risk is addressed by removing privileged HTTP authority from the public endpoint: no posting key on public HTTP, no cookies, no credentialed CORS, no user-specific private data, and deployment-owned TLS/host routing.
• Revisit when: Adding HTTP signing, cookies, credentialed CORS, private/user-specific data, authenticated sessions or private-network access.

JSON-RPC batching

• Status: Implemented
• Priority: Monitor
• Spec point: MCP 2025-06-18 removed support for JSON-RPC batching.
• Current behavior: JSON array request bodies are rejected at the Express /mcp boundary before reaching the SDK transport.
• Decision: Keep batching unsupported.
• Why: The project has no batching use case, and accepting SDK-inherited batches would conflict with 2025-06-18.
• Revisit when: A future MCP version reintroduces batching. Keep regression tests for batch-array rejection.

HTTP lifecycle

• Status: Stateless compatibility mode
• Priority: Next
• Spec point: Initialization MUST be the first interaction.
• Current behavior: In stateless HTTP mode, a direct request such as tools/list can succeed without prior initialize because each POST builds a fresh server/transport and no session state is kept.
• Decision: Decide between stateful Streamable HTTP sessions and accurately documented stateless compatibility mode.
• Why: Enforcing lifecycle strictly may require server-side session state or a different transport construction pattern. This needs a design pass to avoid breaking common clients.
• Revisit when: Evaluating StreamableHTTPServerTransport stateful mode, session storage, /readyz behavior, client compatibility and deployment cost.

HTTP protocol-version header

• Status: Stateless compatibility mode
• Priority: Next
• Spec point: For HTTP after initialization, clients must include MCP-Protocol-Version; unsupported values should be rejected.
• Current behavior: The SDK rejects unsupported explicit values but accepts missing headers. In this app's stateless mode, post-initialization state is not tracked, so the server cannot know whether a request is subsequent to initialization.
• Decision: Revisit together with HTTP lifecycle/session design.
• Why: This is difficult to enforce meaningfully without session state. It is also primarily a client MUST, but server acceptance weakens strict transport-conformance claims.
• Revisit when: If stateful HTTP is adopted, test missing/invalid protocol headers after initialization. If stateless remains, document this as an intentional compatibility mode.

Protocol version target

• Status: Monitor
• Priority: Monitor
• Spec point: Server response should negotiate a supported protocol version.
• Current behavior: SDK 1.29.0 has latest protocol 2025-11-25; it returns 2025-06-18 when requested, 2025-11-25 when requested, and 2025-11-25 for unknown versions.
• Decision: Do not say the server exclusively targets 2025-06-18. Say it supports clients negotiating 2025-06-18 for implemented features.
• Why: The dependency may support newer protocol versions before this project has audited their full behavior.
• Revisit when: On SDK upgrades, record SDK latest/supported versions and rerun raw initialize probes for 2025-06-18, SDK latest and an unknown version.

Streamable HTTP GET/SSE standalone stream

• Status: Optional deferred
• Priority: Later
• Spec point: Streamable HTTP supports POST and GET with optional SSE for server-to-client messages.
• Current behavior: GET /mcp returns 405; POST responses may use SSE per request.
• Decision: Keep unsupported until the server has server-initiated requests/notifications that require standalone GET/SSE.
• Why: Current public endpoint is request/response oriented and does not need server-initiated sampling, roots, elicitation or live notifications. Supporting GET streams would add operational complexity.
• Revisit when: Server-initiated notifications or subscriptions are introduced.

Authorization for HTTP

• Status: Optional deferred
• Priority: Later
• Spec point: MCP HTTP authorization is optional, but protected HTTP servers that support MCP authorization should follow the authorization spec and Protected Resource Metadata requirements.
• Current behavior: Public HTTP endpoint is unauthenticated; write signing over HTTP is refused unless an explicit unsafe trusted-deployment override is set. No OAuth resource-server metadata is implemented.
• Decision: Do not implement MCP OAuth until user-specific/private capabilities or protected hosted deployments exist.
• Why: Current public endpoint exposes public Blurt blockchain data only. Deployment-specific auth can live at the reverse proxy/gateway layer for now.
• Revisit when: The hosted service becomes protected or user-specific.

Tools capability

• Status: Implemented
• Priority: Monitor
• Spec point: Servers that support tools must declare tools; tools/list and tools/call define tool metadata, inputs and results.
• Current behavior: Implemented via McpServer.registerTool; initialize advertises tools: { listChanged: true }; tools include name, title, description, inputSchema, outputSchema, annotations and structured results.
• Decision: Keep as the core supported feature.
• Why: Tools are the main product surface.
• Revisit when: The SDK is upgraded or generated tool contracts change.

Tool list pagination

• Status: Optional deferred
• Priority: Later
• Spec point: tools/list supports cursor pagination.
• Current behavior: The SDK returns all registered tools in one response with no nextCursor. The list is small and static.
• Decision: Do not implement custom pagination unless the tool list becomes large or SDK behavior changes.
• Why: Pagination adds no value for the current tool set.
• Revisit when: Tool count grows substantially.

Tool list change notifications

• Status: Monitor
• Priority: Monitor
• Spec point: If listChanged is declared, servers should notify when the tool list changes.
• Current behavior: SDK high-level API advertises tools: { listChanged: true }; this server's tool list is fixed at server construction and does not change at runtime.
• Decision: Accept as harmless for static tool lists.
• Why: No runtime change occurs, so no notification is needed. If future runtime changes are added, notifications become important.
• Revisit when: Dynamic tool enable/disable is added after initialization; add list-changed notifications or stop advertising the capability if the SDK allows.

Structured tool output

• Status: Implemented
• Priority: Monitor
• Spec point: MCP 2025-06-18 supports structuredContent and optional outputSchema.
• Current behavior: Successful tool results use withStandardStructuredContent; errors return isError with text.
• Decision: Keep structured output.
• Why: Structured output is valuable for agents and generated contract docs.
• Revisit when: The project is ready to make stronger per-tool schema compatibility promises.

Resources and resource templates

• Status: Implemented
• Priority: Monitor
• Spec point: Servers that support resources must declare resources; templates are exposed via resources/templates/list; resources are read with resources/read.
• Current behavior: Four blurt:// resource templates are implemented. Initialize advertises resources: { listChanged: true }.
• Decision: Keep as a supported feature.
• Why: Resource templates are useful for connector-style search/fetch workflows.
• Revisit when: SDK upgrades affect resource URI templates or reads.

Resource listing behavior

• Status: Optional deferred
• Priority: Later
• Spec point: Resource list/template list supports pagination and may list concrete resources.
• Current behavior: Templates are listed; concrete resource listing is effectively empty because templates use { list: undefined }. No cursor pagination is provided.
• Decision: Keep a template-first model; do not list all possible Blurt blockchain resources.
• Why: Blurt blockchain resources are unbounded. Concrete listing would be artificial or expensive.
• Revisit when: Curated resource lists are added; define stable pagination and freshness rules first.

Resource subscriptions

• Status: Out of scope
• Priority: Won't implement
• Spec point: Resource capability may support subscribe; servers that support it send notifications/resources/updated.
• Current behavior: Not advertised and not implemented.
• Decision: Do not implement until there is a concrete live-update product need.
• Why: Public Blurt blockchain queries are request/response; subscriptions would require state, polling and operational commitments.
• Revisit when: Live notifications or watch-style features become a product goal.

Prompts

• Status: Out of scope
• Priority: Won't implement
• Spec point: Servers may expose user-controlled prompt templates.
• Current behavior: Not advertised and not implemented.
• Decision: Do not implement for now.
• Why: This server's role is data/tools, not prompt-template distribution. Human examples live in docs, not MCP prompt objects.
• Revisit when: The project needs curated Blurt analysis workflows as selectable client prompts.

Completion

• Status: Optional deferred
• Priority: Later
• Spec point: Servers may support argument completion for prompts/resources.
• Current behavior: Not advertised and not implemented.
• Decision: Defer.
• Why: Completion would be useful only after prompts or richer resource browsing need it.
• Revisit when: Prompts or curated resources are introduced.

MCP logging

• Status: Optional deferred
• Priority: Later
• Spec point: Servers may advertise logging and send notifications/message; logs must avoid secrets.
• Current behavior: Not advertised. Server logs go to stderr / process logs, not MCP client logging notifications.
• Decision: Keep operational logs outside MCP for now.
• Why: MCP logging is not required for current clients and may expose implementation details if done casually.
• Revisit when: Designing MCP-visible logging with explicit redaction and log-level behavior.

Ping

• Status: Implemented by SDK
• Priority: Monitor
• Spec point: Either party may send ping; receiver must respond promptly.
• Current behavior: Implemented by the SDK default handler.
• Decision: Keep inherited SDK behavior.
• Why: No custom project code is required.
• Revisit when: Lifecycle or transport code changes; include ping in future raw protocol smoke tests.

Cancellation

• Status: Optional deferred
• Priority: Later
• Spec point: Cancellation notifications are optional; receivers should stop processing where possible and may ignore non-cancellable work.
• Current behavior: SDK handles notification plumbing; Blurt RPC calls are not actively aborted by project handlers.
• Decision: Defer active cancellation until long-running tools or abortable RPC wrappers justify it.
• Why: Most calls are short RPC queries; adding cancellation plumbing now would add complexity with limited value.
• Revisit when: Long-running tools are added; pass abort signals to RPC/fetch layers and test cancellation.

Progress notifications

• Status: Out of scope
• Priority: Won't implement
• Spec point: Progress is optional for long-running operations.
• Current behavior: Not emitted by tools.
• Decision: Do not implement for current short request/response tools.
• Why: Current operations do not have meaningful progress stages.
• Revisit when: Long-running scans, exports or batch workflows are introduced.

Sampling, roots and elicitation

• Status: Out of scope
• Priority: Won't implement
• Spec point: Server-initiated client features are optional and require negotiated client capabilities.
• Current behavior: Not used.
• Decision: Keep out of scope.
• Why: The server does not need model calls, filesystem roots or interactive elicitation to expose public Blurt blockchain data.
• Revisit when: A new feature explicitly needs client-provided roots, sampling or user elicitation.

Error style for tool failures

• Status: Implemented
• Priority: Monitor
• Spec point: Tool calls may return tool-level isError results; transport errors should be reserved for protocol failures.
• Current behavior: Most tool failures return isError: true with text; protocol/schema failures are handled by the SDK.
• Decision: Keep this behavior.
• Why: AI clients can recover from data/API failures without treating the MCP session as broken.
• Revisit when: Error formatting changes; continue avoiding secret leakage in error text.

Maintenance procedure

When reviewing this register:

1. Fetch the exact MCP specification version under review.
2. Record the installed @modelcontextprotocol/sdk version, LATEST_PROTOCOL_VERSION and supported versions.
3. Probe the live app with raw protocol requests for:
   • initialize with the target version;
   • initialize with SDK latest;
   • unknown protocol version;
   • direct operation before initialize;
   • batch request body;
   • HTTP Origin behavior;
   • missing/invalid MCP-Protocol-Version header where applicable.
4. Compare advertised capabilities with implemented handlers.
5. Update every affected record with a status, decision and priority.
6. Update public wording if the support/conformance statement changes.

Current publication wording

Use this wording until a stricter audit proves broader conformance:

This server uses the Model Context Protocol TypeScript SDK and supports MCP clients negotiating protocol version 2025-06-18 for its implemented tools and resource-template features.