MCP_SSE_COMPATIBILITY.md•3 kB
# MCP Inspector Compatibility for HTTP/SSE Transport
## Overview
This document explains the changes made to ensure compatibility between Atrax's HTTP/SSE transport implementation and the MCP Inspector tool.
## Key Changes
1. **SDK-Compatible Implementation**: Created an adapter around the SDK's `SSEServerTransport` to maintain type compatibility with our system while ensuring the SDK's transport is used for protocol compatibility.
2. **Session ID in Endpoint Event**: Updated the SSE endpoint to include the session ID in the endpoint event data:
```javascript
// Changed from:
res.write(`event: endpoint\ndata: /message\n\n`);
// To:
res.write(`event: endpoint\ndata: /message?sessionId=${clientId}\n\n`);
```
3. **Session Management**: Improved the session tracking mechanism to work directly with the SDK's transport handling.
4. **Header Configuration**: Ensured proper headers are set for SSE connections, particularly for CORS.
## Implementation Details
### HTTPHandler Class Changes
1. **Session Management & Adapter Pattern**: Created an adapter to bridge our Transport interface with the SDK's implementation:
```typescript
private sessions: Map<string, {
transport: SdkSSEServerTransport;
adapter: TransportAdapter;
createdAt: Date;
}> = new Map();
```
2. **SSE Connection Handling**: Modified the `handleSSE` method to:
- Use the SDK's transport directly
- Send the endpoint event with session ID
- Send headers in the correct order
3. **Message Routing**: Updated the `handleMessage` method to properly extract the session ID from query parameters and route requests to the correct transport.
### TransportAdapter Implementation
1. **Adapter Pattern**: Created an adapter that implements our Transport interface but delegates to the SDK's SSEServerTransport:
```typescript
class TransportAdapter implements Transport {
private transport: SdkSSEServerTransport;
constructor(transport: SdkSSEServerTransport, clientId: string) {
this.transport = transport;
// ...setup event forwarding...
}
// Implement Transport interface methods by delegating to SDK transport
}
```
2. **Improved Transport Management**: Enhanced the transport tracking and removal process with better logging and error handling.
## Testing
To validate these changes, we created test implementations that use the MCP SDK directly and tested them with the MCP Inspector. The key findings were:
1. The MCP Inspector expects the session ID to be included in the endpoint event data (`/message?sessionId=XXX`)
2. The SDK's transport class manages the SSE connection lifecycle properly
3. Headers need to be set before any data is written to the response
## Conclusion
By directly leveraging the SDK's SSE transport implementation and following the protocol more precisely, Atrax now provides better compatibility with the MCP Inspector and other clients that follow the standard MCP protocol.