Skip to content

vMCP: extend backend-init list-method tolerance to HTTP-level method-missing signals #5242

Open

Description

@tgrunnagle

Background

PR #5232 (issue #5231) added narrow tolerance in pkg/vmcp/session/internal/backend/mcp_session.go::initAndQueryCapabilities so that a backend advertising the resources or prompts capability but returning JSON-RPC -32601 (method not found) for resources/list / prompts/list no longer aborts backend init and silently drops every tool from that backend.

That fix is intentionally scoped to JSON-RPC -32601 envelopes only. The recovery comment now explicitly states "HTTP-level method absence is intentionally fatal" — review thread: #5232 (comment).

Problem

Some real-world backends sit behind reverse proxies, API gateways, or non-MCP front doors that surface "this method isn't implemented" as an HTTP-level response (404 / 405 / 501) rather than as a JSON-RPC -32601 envelope. Under those conditions:

  • mcp-go's streamable-HTTP / SSE transport layers return a non-sentinel transport error (not wrapping mcp.ErrMethodNotFound).
  • errors.Is(listErr, mcp.ErrMethodNotFound) therefore evaluates false.
  • The fatal case listErr != nil arm fires → init aborts → every tool from that backend is silently dropped.

This reproduces the original #5231 symptom for a slightly different class of misbehaving backends.

Proposed work

  1. Enumerate the transport-level signals to be treated as method-missing. Candidates: HTTP 404 Not Found, 405 Method Not Allowed, 501 Not Implemented.
  2. Decide where the discrimination happens — at the adapter / transport boundary (preferred, keeps pkg/vmcp/session/internal/backend clean) versus inside initAndQueryCapabilities.
  3. Extend the existing errors.Is(listErr, mcp.ErrMethodNotFound) case in mcp_session.go (or replace it with a richer predicate) so the chosen transport-level errors recover with the same WARN-and-continue behavior as -32601.
  4. Add tests that exercise each chosen HTTP status against the existing fakeBackend harness in mcp_session_capabilities_test.go.
  5. Keep tools/list strict — recovery should remain limited to resources/list and prompts/list, matching the scope of vMCP backend init fails fatally when server advertises resources capability without resources/list #5231.

Acceptance criteria

  • Concrete list of HTTP statuses recovered, documented in the recovery comment alongside the existing -32601 note.
  • Recovery path emits the same slog.Warn breadcrumb (backendID / name / baseURL / method) as the JSON-RPC -32601 path.
  • Backend with tools + resources capabilities and resources/list returning HTTP 404/405/501 still initializes successfully and exposes its tools.
  • Backend with tools/list returning HTTP 404/405/501 still aborts init (regression guard).
  • Unit tests added for each recovered status.

References

Activity

  1. hellouz818 commented on Sep 14, 2026

    @hellouz818
    Contributor

    Hi, I'd like to work on this.

    I'm also looking at #6339, which is related but separate. I'll address the two issues in separate PRs to keep the fixes and reviews focused.

    For this issue, I plan to extend the existing -32601 recovery for resources/list and prompts/list to also tolerate HTTP 404/405/501 responses, with matching unit tests. tools/list will remain strict, as specified in the acceptance criteria.

    I have a production vMCP deployment running ToolHive v0.46.0 with Atlassian and Tableau backends, so I can also validate the behavior against real-world scenarios.

  2. hellouz818 commented on Sep 15, 2026

    @hellouz818
    Contributor

    Hi, #6660 has been merged, which covers JSON-RPC -32601 tolerance for resources/list and prompts/list in the ListCapabilities path.

    This issue extends that handling to HTTP-level method-missing signals (404 / 405 / 501) in the same area. I'd be happy to pick this up and open a PR if no one else is working on it. Please assign this to me if the scope looks right. :)

  3. added a commit that references this issue on Sep 15, 2026
    64dfc12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestgoPull requests that update go codevmcpVirtual MCP Server related issues

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions