elysia

This MCP server provides an HTTP-based implementation of the Model Context Protocol (MCP) for Elysia apps. It enables clients to interact with tools, resources, prompts, and logging through standard HTTP endpoints, with session management preserved via headers. The plugin is TypeScript-enabled and uses Zod for input validation, offering a type-safe experience with proper JSON-RPC 2.0 error handling. To use it, you configure the server with serverInfo, capabilities, and a setupServer callback that registers your MCP tools, resources, and prompts. Once running, you can query and execute registered tools over HTTP, manage sessions via the MCP-Session-Id header, and leverage your preferred logger or the default console logger for visibility into operations and errors. The starter template demonstrates how to wire tools like an echo operation, and the examples show how to expose multiple modular endpoints (e.g., /math, /text) for different plugin areas.

With the included modular handler architecture, you can register tools, resources, and prompts through a centralized MCP server instance and expose them under a base path (default /mcp). You can also run an MCP Inspector to test endpoints and verify behavior against the MCP specification. The plugin supports custom loggers (Pino, Winston, Bunyan, etc.), JSON responses or streaming, stateless mode, and session-aware operation, making it suitable for iterative development and production deployments.

Prerequisites:

• Node.js v14+ (or a compatible runtime) or a Bun-based environment if you prefer Bun-based workflows
• Access to npm, yarn, or Bun for package management
• Basic TypeScript setup if building from source (optional, for advanced customization)

Installation steps:

1. Install the MCP package (example uses npm; you can also use bun or yarn): npm install elysia-mcp

2. If you are starting from the starter template, clone the repository and install dependencies: gh repo clone kerlos/elysia-mcp-starter my-mcp-project cd my-mcp-project npm install

3. Create your MCP server entrypoint (if not using the starter): // path/to/server.js const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js'); // Implement server setup and export or start the HTTP MCP server as per the example in the README

4. Run your server locally (adjust commands as needed for your environment): node path/to/server.js

5. (Optional) If you prefer Bun scripts, you can follow the starter template scripts: bun create https://github.com/kerlos/elysia-mcp-starter my-mcp-project cd my-mcp-project bun install bun run dev

Prerequisites summary:

• Node.js or Bun runtime installed
• MCP package and any peer dependencies installed
• A basic server entrypoint to initialize and run the MCP server over HTTP

Notes and tips:

• The MCP server is designed to run over HTTP with optional streaming support. If you need JSON responses only, enable the appropriate configuration (enableJsonResponse).
• Session management is handled via the MCP-Session-Id header; ensure clients propagate this header for stateful interactions.
• You can customize logging by supplying a logger that implements the ILogger interface, or use the provided default console logger by enabling logging.
• When registering tools/resources/prompts, ensure your input schemas and descriptions are well-documented to improve tool discoverability and validation.
• If you encounter issues with endpoints, check basePath (default /mcp), authentication settings, and the eventStore configuration for resumability features.
• The starter template showcases a multi-server example and how to organize tools under modular paths such as /math and /text. Use MCP Inspector to quickly validate endpoints during development.