mcp-dart-streamable-http

Streamable HTTP servers and clients with mcp_dart

Streamable HTTP is the MCP transport for remote servers, browsers, Flutter Web and mobile apps. StreamableMcpServer serves one endpoint (default /mcp), routes MCP 2026-07-28 requests statelessly and manages sessions for initialization-era (MCP 2025-11-25 and earlier) clients. StreamableHttpClientTransport is the matching client transport. Server APIs need dart:io; the client transport also runs on the web.

Guidelines

• serverFactory runs once per stateless MCP 2026-07-28 request and once per legacy session. Return createMcpServer(services) from it (see the mcp-dart-server project structure) and build application state (databases, caches, clients) once, outside the factory.
• If you change protocol, pass the same McpProtocol to StreamableMcpServer(protocol: ...) and to the factory's McpServerOptions(protocol: ...).
• Leave enableDnsRebindingProtection at its default (true), even on localhost. Set allowedHosts to the exact public hostnames and allowedOrigins to the exact browser origins (https://app.example.com), never wildcards. allowedOrigins also drives credentialed CORS.
• Bind to 127.0.0.1 for local development. StreamableMcpServer listens on plain HTTP: terminate TLS at a reverse proxy or load balancer for remote deployments, and set OAuthProtectedResourceOptions.metadataUri to the public URL when the proxy rewrites scheme, host or port.
• Authenticate with authenticationHandler: (request) => ... returning StreamableMcpAuthenticationResult.allow(), .unauthorized() or .insufficientScope(scope: ...). Verify the token's signature or introspect it, and check issuer, audience/resource, expiry and scopes. Never trust claims from an unverified token. Host/Origin checks run before authentication. Pass a closure: package:mcp_dart/mcp_dart.dart defaults to web-safe exports, so the analyzer types request as dynamic (it is an HttpRequest at runtime on dart:io), and a tear-off typed Function(HttpRequest) fails analysis.
• Configure oauthProtectedResource so failures return 401 with a WWW-Authenticate: Bearer resource_metadata="..." challenge and the metadata is served at /.well-known/oauth-protected-resource/<path>. Without it, a failed check is a generic 403. The boolean authenticator hook remains for simple allow/deny checks.
• Keep the strict defaults (strictProtocolVersionHeaderValidation, rejectBatchJsonRpcPayloads) unless a specific legacy peer requires otherwise. Stop the server with await server.stop().
• Client: pass static headers through StreamableHttpClientTransportOptions(requestInit: {'headers': {...}}) and tokens through an OAuthClientProvider whose tokens() returns OAuthTokens(accessToken: ...). Load tokens from secure storage; never hard-code, log or persist them in plaintext files.
• For interactive OAuth, implement OAuthAuthorizationCodeProvider. The transport discovers protected-resource and authorization-server metadata, builds a PKCE S256 URL and calls redirectToAuthorizationUrl. When the redirect arrives, call transport.finishAuthRedirect(code, state: ..., issuer: ...) with the callback's state (and iss when present), then reconnect. Cross-origin authorization servers must be approved with a narrow oauthUriValidator.
• Legacy HTTP+SSE (SseClientTransport, SseServerManager) is deprecated. Use Streamable HTTP for new integrations.