Merged
Conversation
Implement dual-protocol architecture supporting both STDIO and HTTP transports. HTTP mode enables OpenAI Agent Builder integration with Bearer token authentication and session management. - Create http-server.ts with StreamableHTTPServerTransport - Extract stdio-server.ts from existing implementation - Refactor index.ts to route between transport modes - Add session-based architecture for multi-tenant support - Implement CORS headers for web-based integrations
Replace monolithic implementation with router pattern that supports http, stdio, or default mode selection via CLI arguments.
HTTP mode authenticates via Bearer token from request headers, not environment variables. TAGOIO_TOKEN now defaults to empty string for HTTP compatibility while STDIO mode explicitly validates token presence.
Update MCP SDK to support StreamableHTTPServerTransport and add node crypto types for session ID generation.
Add HTTP mode configuration examples to README and create MCP_HTTP_README.md with technical details on session management, Bearer authentication, OpenAI Agent Builder integration, and testing approaches.
Implements automatic cleanup of inactive sessions based on configurable timeout. Sessions now track last activity timestamp and are automatically cleaned up after the configured inactivity period (default 60 minutes via SESSION_LIVE env var). Cleanup runs every 5 minutes to remove expired sessions and free resources.
vitorfdl
force-pushed
the
TAGOAI-101_Http_Protocol_Support
branch
from
e1d9a6f to
98d1ee2
Compare
In HTTP mode, authentication is handled via Bearer token in request headers instead of environment variables, so TAGOIO_TOKEN should default to empty string.
Add integration test suite for the HTTP server covering session lifecycle, authentication, CORS, SSE streams, and tool calls. Add start:http and test:http npm scripts to run the server and tests end-to-end.
…ADME Update tool references from device-list to device-operations with correct argument structure. Fix unclosed JSON in curl examples and align capabilities response and SessionData interface with actual implementation.
…types Add stdio-server.test.ts with 8 integration tests covering session init, tool calls, error handling, and concurrent requests. Extract JsonRpcRequest and JsonRpcResponse into shared types.ts used by both test files.
Vitest 4.x is ESM-only and breaks CI with ERR_REQUIRE_ESM in CommonJS projects. Zod 4.x changed error messages breaking existing tests.
The project requires Node.js >=20 as specified in package.json engines field.
Align CI with the Node.js version used in development and production.
Unified server config (name, version, instructions) across STDIO and HTTP transports. Added per-request region support via x-tagoio-region header (us-e1, eu-w1). Fixed CORS headers to allow mcp-protocol-version for MCP Inspector compatibility. Removed token logging and delegated GET/DELETE to SDK transport for proper stateless mode handling.
- Extract shared CORS/auth/region utilities into server/shared.ts
- Differentiate auth failures from infrastructure errors in validateTagoToken
- Add 1MB body size limit to prevent DoS via unbounded request bodies
- Return proper 400/413 responses for malformed JSON and oversized payloads
- Close MCP server and transport after each request to prevent memory leaks
- Add try-catch with structured JSON-RPC error responses in Lambda handler
- Add server.on('error') handler for EADDRINUSE and MCP_PORT validation
- Add .catch() on main() to handle unhandled startup rejections
- Preserve original error details in stdio server connection failures
- Move path check before OPTIONS to restrict CORS preflight to /mcp
- Remove unused headersModel from config.model.ts
- Add vitest unit tests for shared utilities and Lambda handler (25 tests)
- Replaced `extractBearerToken` with `extractToken` to support both Bearer and raw token formats. - Updated error messages in HTTP and Lambda handlers for clarity. - Enhanced README with clearer instructions on token usage and server setup. - Adjusted TypeScript configurations for consistency and improved type imports. - Cleaned up code formatting and removed unused region validation logic.
- Modified npm_publish.yml and tests.yml to use Node.js version 24.x for consistency across CI environments.
- Upgraded various dependencies in package.json and package-lock.json, including @modelcontextprotocol/sdk to ^1.29.0, @tago-io/sdk to ^12.2.2, zod to ^4.3.6, and typescript to ^6.0.2. - Updated Node.js version requirement from >=20 to >=24 in package.json and README.md for consistency. - Adjusted devDependencies to reflect the latest versions for @types/aws-lambda, aws-cdk-lib, constructs, vitest, and biome. - Refactored import statements in several files to use zod from 'zod/v3' for compatibility with the updated version.
Replace unplugin-swc with Vitest 4.x built-in Oxc transformer. Use function expression instead of arrow function in mock constructor to satisfy Vitest 4.x stricter new-target behavior.
- Changed Node.js version requirement from >=24 to >=22 in package.json and package-lock.json for compatibility. - Removed unneeded dependency on unplugin-swc from package.json and package-lock.json. - Enhanced README with additional installation instructions and health check endpoint details for improved clarity. - Added health check endpoint to the HTTP server for better monitoring and status reporting.
… files - Bumped version from 2.1.4 to 3.0.0 in package.json, package-lock.json, server.json, and utils/server-config.ts. - Updated README to reflect the new package name for CLI usage. - Standardized server name in configuration to align with the new versioning.
vitorfdl
previously approved these changes
Apr 14, 2026
Replace all raw console.error calls with a centralized logger that respects the LOG_LEVEL env var. Token validation failures are logged at warn level to avoid flooding CloudWatch on public Lambda deployments.
Arrow functions cannot be called with `new`, causing 4 test failures in lambda-handler tests.
…ction handling - Changed server startup to use `tsx` for better compatibility. - Enhanced shutdown process to gracefully handle active connections, with a timeout for forced shutdown. - Added connection tracking to ensure all sockets are properly closed during server shutdown.
…accessibility - Replaced placeholder comments with actual installation badges for VS Code, VS Code Insiders, Visual Studio, Cursor, and LM Studio. - Updated links to direct users to the appropriate installation pages with configuration details.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The MCP server only supported STDIO transport, limiting usage to local CLI environments and preventing integration with web-based clients like OpenAI Agent Builder that require HTTP endpoints.
Investigation
Solution
Transport Architecture
stdioandhttpmodesStreamableHTTPServerTransportAuthentication & Security
Authorizationheader for HTTP modemcp-session-idheader for request correlationTAGOIO_TOKENenvironment variable optional (only required for STDIO)Session Management
SESSION_LIVEenvironment variableDocumentation
MCP_HTTP_README.md)Dependencies
@modelcontextprotocol/sdkto support Streamable HTTP transportCloses #14