mcp-boilerplate

This MCP server boilerplate implements the Model Context Protocol (MCP) over SSE (Server-Sent Events) and ships with a ready-to-extend structure. It includes an example tool called calculator that can perform basic arithmetic operations (add, subtract, multiply, divide). Clients connect via the /sse endpoint using an API key for authentication and can then invoke tools or receive streamed updates through MCP-compatible transports. The server supports session management, configurable keepalive/ping behavior, and structured logging. To get started, configure your environment variables (PORT, HOST, and API_KEY) and run the server. Once running, clients can connect to /sse, authenticate with the API key, and start sending tool requests or subscribe to tool events as per the MCP protocol. The README’s extension guide also shows how to add your own tools by editing the tool configurations and handlers in src/tools.*.

Prerequisites:

• Node.js and npm installed
• A TypeScript project setup (the boilerplate ships with tsconfig and src/ folders)

Setup steps:

1. Install dependencies

npm install

2. Create a .env file (optional but recommended) with API_KEY, PORT, and HOST values:

PORT=4005
API_KEY=your_api_key
HOST=localhost

3. Build the project (transpile TypeScript to JavaScript)

npm run build

4. Start the server (SSE mode as per the README examples)

npm run start:sse

Notes:

• You can customize the port and host by editing the environment variables or the config if needed.
• The server exposes endpoints such as /health, /sse, and /messages; ensure your client uses the /sse endpoint with the API_KEY parameter.

Tips and considerations:

• Ensure API_KEY is kept secure; it is required for all connections.
• If you encounter Body timeout errors, adjust keepaliveInterval and enable usePingEvents as described in the Troubleshooting SSE Timeouts section.
• When adding custom tools, follow the example in Extending the boilerplate by updating src/tools.ts, adding a ToolConfig with name, description, inputSchema, and handler.
• For production deployment, consider using a process manager (PM2) and/or Docker as described in your deployment workflow.
• The server supports graceful shutdown on SIGINT and SIGTERM; ensure your deployment environment forwards these signals correctly.