refactor: drop legacy SSE transport, streamable HTTP only (#1428)

Author: bjcoombs

Tiltfile

@@ -617,7 +617,7 @@ k8s_resource(
 # MCP Server
 # =============================================================================
 # Model Context Protocol server for AI agent integration.
-# Exposes Meridian's transaction engine capabilities via MCP SSE transport.
+# Exposes Meridian's transaction engine capabilities via streamable HTTP transport.
 # Connects to the gateway for all backend gRPC service calls.
 
 # Standard build args for mcp-server
@@ -644,7 +644,7 @@ k8s_yaml('services/mcp-server/k8s/service.yaml')
 # Configure mcp-server resource
 k8s_resource(
     'mcp-server',
-    port_forwards=['18090:8090'],  # MCP SSE endpoint (18090 to avoid conflict with gateway)
+    port_forwards=['18090:8090'],  # MCP HTTP endpoint (18090 to avoid conflict with gateway)
     resource_deps=[
         'generate-proto',   # Ensures proto files are generated before building
         'gateway',          # MCP server routes all gRPC calls through the gateway
@@ -991,7 +991,7 @@ Gateway:
   • HTTP Gateway           → localhost:8090 (subdomain routing)
     - Tenant resolution via TenantResolverMiddleware
     - Proxies to gRPC backends via Connect protocol
-  • MCP Server             → localhost:18090 (SSE transport)
+  • MCP Server             → localhost:18090 (streamable HTTP)
     - Model Context Protocol for AI agent integration
     - Routes all gRPC calls through the HTTP gateway
 

deploy/demo/.env.demo.example

@@ -163,7 +163,7 @@ DEPOSIT_CLEARING_ACCOUNT_ID=CLEARING-GBP-001
 # MCP Server (AI Integration)
 # ---------------------------------------------------------------------------
 
-# [REQUIRED] Public base URL for MCP OAuth callbacks and SSE endpoint discovery.
+# [REQUIRED] Public base URL for MCP OAuth callbacks.
 MCP_BASE_URL=https://demo.meridianhub.cloud
 
 # [REQUIRED] API key for MCP server to authenticate with Meridian gRPC API.

deploy/demo/Caddyfile

@@ -22,9 +22,9 @@ demo.meridianhub.cloud, *.demo.meridianhub.cloud {
 		respond "Not Found" 404
 	}
 
-	# MCP Server: streamable HTTP + legacy SSE transport
+	# MCP Server: streamable HTTP transport
 	@mcp_transport {
-		path /mcp /mcp/* /sse /sse/* /message /message/*
+		path /mcp /mcp/*
 	}
 	handle @mcp_transport {
 		reverse_proxy mcp-server:8090

deploy/demo/docker-compose.yml

@@ -121,8 +121,8 @@ services:
         condition: service_started
     environment:
       # --- MCP Transport ---
-      MCP_TRANSPORT: sse
-      MCP_SSE_PORT: "8090"
+      MCP_TRANSPORT: http
+      MCP_PORT: "8090"
       MCP_SERVER_NAME: ${MCP_SERVER_NAME:-meridian-mcp}
       MCP_BASE_URL: ${MCP_BASE_URL:?MCP_BASE_URL must be set in the env file (e.g. https://your-domain)}
 
@@ -138,7 +138,7 @@ services:
       MCP_OAUTH_CLIENT_ID: ${MCP_OAUTH_CLIENT_ID:-}      # required when MCP_OAUTH_ENABLED=true
       MCP_OAUTH_REDIRECT_URI: ${MCP_OAUTH_REDIRECT_URI:-} # required when MCP_OAUTH_ENABLED=true
     # Not exposed to host — accessed only by caddy on the internal network
-    # Caddy proxies /sse and /message to this container
+    # Caddy proxies /mcp to this container
 
   caddy:
     image: caddy:2-alpine

deploy/dev/docker-compose.yml

@@ -18,7 +18,7 @@
 #   50051 - meridian gRPC
 #   8090  - meridian HTTP gateway
 #   5173  - frontend (Vite dev server)
-#   8091  - mcp-server SSE endpoint
+#   8091  - mcp-server HTTP endpoint
 #   50064 - financial-gateway gRPC
 
 services:
@@ -114,8 +114,8 @@ services:
       - "127.0.0.1:8091:8090"
     environment:
       LOG_LEVEL: info
-      MCP_TRANSPORT: sse
-      MCP_SSE_PORT: "8090"
+      MCP_TRANSPORT: http
+      MCP_PORT: "8090"
       MCP_SERVER_NAME: meridian-mcp
       MCP_BASE_URL: http://localhost:8091
       MERIDIAN_API_URL: meridian:50051

services/mcp-server/README.md

@@ -12,10 +12,10 @@ instructions: |
   using the Model Context Protocol (MCP 2025-03-26).
 
   Key patterns:
-  - Transport agnostic: stdio for CLI tools, streamable HTTP for network clients (recommended), SSE for legacy clients
+  - Transport modes: stdio for CLI tools, streamable HTTP for network clients
   - Tool categories: Read (no side effects), Simulate (dry-run), Write (state mutation)
   - Plan-before-apply safety: meridian_manifest_plan must precede meridian_manifest_apply
-  - OAuth 2.1 with PKCE: optional, enabled via MCP_OAUTH_ENABLED=true for network transports
+  - OAuth 2.1 with PKCE: optional, enabled via MCP_OAUTH_ENABLED=true for HTTP transport
   - All logs go to stderr; stdout is reserved for the JSON-RPC protocol (stdio mode)
 ---
 
@@ -31,8 +31,8 @@ Thin JSON-RPC adapter that exposes Meridian's backend services to LLM clients vi
 | **Type** | Infrastructure (API Gateway) |
 | **Language** | Go |
 | **Protocol** | MCP 2025-03-26 |
-| **Transports** | stdio, streamable HTTP, SSE (legacy) |
-| **Auth** | OAuth 2.1 with PKCE (optional, network transports) |
+| **Transports** | stdio, streamable HTTP |
+| **Auth** | OAuth 2.1 with PKCE (optional, HTTP transport) |
 | **Standalone** | No (requires Meridian backend services via `MERIDIAN_API_URL`) |
 
 ## Architecture
@@ -51,7 +51,6 @@ flowchart TB
     subgraph "MCP Server"
         ST[stdio Transport]
         SH[Streamable HTTP Transport]
-        SE[SSE Transport - Legacy]
         TH[Tool Handlers]
         RH[Resource Handlers]
         PH[Prompt Handlers]
@@ -72,11 +71,9 @@ flowchart TB
     CLI -->|JSON-RPC| ST
     CB -->|JSON-RPC + Bearer| SH
     SH <--> OA
-    SE <--> OA
 
     ST --> TH
     SH --> TH
-    SE --> TH
     TH --> RH
     TH --> PH
 
@@ -100,7 +97,7 @@ responses to stdout. Logs are written to stderr to avoid corrupting the protocol
 MCP_TRANSPORT=stdio ./mcp-server
 ```
 
-### Streamable HTTP (recommended for network deployments)
+### Streamable HTTP (for network deployments)
 
 The streamable HTTP transport (MCP spec 2025-03-26) uses a single `/mcp` endpoint for all
 communication. Clients POST JSON-RPC requests and receive synchronous JSON responses. Session
@@ -111,36 +108,19 @@ management is handled via the `Mcp-Session-Id` header.
 | `/mcp` | `POST` | Send JSON-RPC requests (initialize, tools/list, tools/call, etc.) |
 | `/mcp` | `DELETE` | Terminate a session |
 
-The streamable HTTP transport is automatically available alongside SSE when running in `sse`
-mode -- no separate transport flag is needed.
-
 ```bash
-MCP_TRANSPORT=sse MCP_SSE_PORT=8090 ./mcp-server
-# Both /mcp (streamable HTTP) and /sse + /message (legacy) are served
-```
-
-### SSE (legacy)
-
-The original SSE transport is still available for clients that do not yet support streamable HTTP.
-
-| Endpoint | Purpose |
-|----------|---------|
-| `GET /sse` | Establishes the SSE stream for server-to-client messages |
-| `POST /message` | Receives client JSON-RPC requests |
-
-```bash
-MCP_TRANSPORT=sse MCP_SSE_PORT=8090 ./mcp-server
+MCP_TRANSPORT=http MCP_PORT=8090 ./mcp-server
 ```
 
 ## Environment Variables
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `sse` |
-| `MCP_SSE_PORT` | `8090` | HTTP port when using SSE transport |
+| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
+| `MCP_PORT` | `8090` | HTTP port when using streamable HTTP transport |
 | `MCP_SERVER_NAME` | `meridian-mcp` | Server name reported in MCP initialize response |
-| `MCP_BASE_URL` | `http://localhost:8090` | Base URL for OAuth redirect URIs (SSE mode) |
-| `MCP_OAUTH_ENABLED` | `false` | Enable OAuth 2.1 PKCE flow for SSE transport |
+| `MCP_BASE_URL` | `http://localhost:8090` | Base URL for OAuth redirect URIs (HTTP mode) |
+| `MCP_OAUTH_ENABLED` | `false` | Enable OAuth 2.1 PKCE flow for HTTP transport |
 | `MCP_OAUTH_CLIENT_ID` | `meridian-mcp` | OAuth client ID advertised to clients |
 | `MCP_OAUTH_REDIRECT_URI` | `{MCP_BASE_URL}/oauth/callback` | OAuth redirect URI |
 | `MERIDIAN_API_URL` | - | gRPC address of the Meridian gateway (e.g., `localhost:9090`) |
@@ -149,15 +129,15 @@ MCP_TRANSPORT=sse MCP_SSE_PORT=8090 ./mcp-server
 
 ## OAuth 2.1 Configuration
 
-OAuth 2.1 with PKCE is optional and applies to both the streamable HTTP and SSE transports. When
-enabled, the server exposes authorization and token endpoints and requires clients to present a
-bearer token on the `/mcp`, `/sse`, and `/message` endpoints.
+OAuth 2.1 with PKCE is optional and applies to the streamable HTTP transport. When enabled, the
+server exposes authorization and token endpoints and requires clients to present a bearer token
+on the `/mcp` endpoint.
 
-Example configuration for a production SSE deployment:
+Example configuration for a production deployment:
 
 ```bash
-MCP_TRANSPORT=sse
-MCP_SSE_PORT=8090
+MCP_TRANSPORT=http
+MCP_PORT=8090
 MCP_BASE_URL=https://mcp.example.com
 MCP_OAUTH_ENABLED=true
 MCP_OAUTH_CLIENT_ID=my-mcp-client
@@ -176,7 +156,7 @@ For production, configure a real JWT signer and validator.
 
 ## Client Configuration
 
-### Streamable HTTP (recommended for network deployments)
+### Streamable HTTP (for network deployments)
 
 For Claude Desktop, Claude Code, or any MCP client connecting to a remote Meridian instance:
 
@@ -191,7 +171,7 @@ For Claude Desktop, Claude Code, or any MCP client connecting to a remote Meridi
 }
 ```
 
-### stdio mode (recommended for local development)
+### stdio mode (for local development)
 
 Add the following to your Claude Desktop configuration file
 (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
@@ -212,18 +192,6 @@ Add the following to your Claude Desktop configuration file
 }
 ```
 
-### Legacy SSE (for clients without streamable HTTP support)
-
-```json
-{
-  "mcpServers": {
-    "meridian": {
-      "url": "http://localhost:8090/sse"
-    }
-  }
-}
-```
-
 ## Available Tools
 
 Tools are grouped into three categories:
@@ -334,20 +302,18 @@ MERIDIAN_API_URL=localhost:9090 \
   /tmp/meridian-mcp
 ```
 
-### Running standalone (network mode)
+### Running standalone (HTTP mode)
 
 ```bash
-MCP_TRANSPORT=sse \
-  MCP_SSE_PORT=8090 \
+MCP_TRANSPORT=http \
+  MCP_PORT=8090 \
   MERIDIAN_API_URL=localhost:9090 \
   MERIDIAN_API_KEY=pk_your_tenant_api_key \
   LOG_LEVEL=debug \
   /tmp/meridian-mcp
 ```
 
-This starts both the streamable HTTP (`/mcp`) and legacy SSE (`/sse`, `/message`) endpoints.
-
-Test with curl using the streamable HTTP transport:
+Test with curl:
 
 ```bash
 # Initialize a session
@@ -362,18 +328,6 @@ curl -X POST http://localhost:8090/mcp \
   -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
 ```
 
-Or test with the legacy SSE transport:
-
-```bash
-# Open SSE stream
-curl -N http://localhost:8090/sse
-
-# Send a tools/list request (in a separate terminal)
-curl -X POST http://localhost:8090/message \
-  -H 'Content-Type: application/json' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
-```
-
 ## References
 
 - [Services Architecture](../README.md)

services/mcp-server/cmd/Dockerfile

@@ -47,7 +47,7 @@ COPY --from=builder /build/mcp-server /mcp-server
 # Use non-root user (distroless provides nonroot user at uid 65532)
 USER nonroot:nonroot
 
-# Expose SSE port (only used when MCP_TRANSPORT=sse)
+# Expose HTTP port (used when MCP_TRANSPORT=http)
 EXPOSE 8090
 
 # Run the binary