Skip to content

test: Add raw-HTTP streamable-transport protocol-compliance suite #918

@jirispilka

Description

@jirispilka

Context

Our integration tests today all go through the official MCP SDK client. The SDK is a well-behaved client and intentionally hides three things our streamable-HTTP transport contract still needs assertions on. This issue tracks adding a narrow raw-HTTP suite for exactly those things.

Companion issue in apify-mcp-server-internal: apify/apify-mcp-server-internal#566 (covers the hosted-only slice — auth 401, Origin, Redis-backed session lookup).

Why raw HTTP

The SDK hides:

  1. HTTP status codes (200/202/400/404). The SDK surfaces JSON-RPC errors but not the codes; ops dashboards, load balancers, and the SDK's own session-recovery logic key off them.
  2. HTTP-only headers (Mcp-Session-Id, future MCP-Protocol-Version enforcement). The SDK manages these internally; a client can't read them.
  3. Misbehavior the SDK refuses to do — no session, malformed JSON. These come from broken proxies, fuzzers, browser dev tools, and other-language clients.

Anything inside the SDK's happy path (ping, capability errors, tool-not-found, pagination, structured output) stays SDK-mediated in tests/integration/suite.ts.

Tests to add

Initialization & session lifecycle

  • initialize returns 200 and an Mcp-Session-Id header (visible ASCII per spec)
  • POST without Mcp-Session-Id (and not initialize) → 400
  • POST with unknown Mcp-Session-Id → 404 so SDK recovery starts a new session
  • DELETE on a valid session → 2xx; reusing the same session ID afterwards → 404

HTTP envelope

  • Notification posts → HTTP 202 with empty body
  • notifications/cancelled for an unknown requestId → 202 (silent no-op per spec)
  • Malformed JSON body → 4xx

Protocol-version negotiation

  • Subsequent requests with an unsupported MCP-Protocol-Version header → 400

Scope boundary

Tests that depend on hosted-stack behavior (auth 401, WWW-Authenticate, foreign-origin 403, Redis-backed cross-node session lookup) live in apify-mcp-server-internal — see apify/apify-mcp-server-internal#566.

Implementation notes

A small (~150 LOC) raw-HTTP helper plus a single new test file alongside tests/integration/suite.ts. A drafted client lives at apify/apify-mcp-server-internal#474 (closed) and can be ported as a starting point.

Metadata

Metadata

Assignees

No one assigned

    Labels

    t-aiIssues owned by the AI team.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions