MCP Boilerplate Server

You deploy and run a Model Context Protocol (MCP) server that exposes a standard SSE-based transport for connecting AI models to data sources and tools. This boilerplate provides authentication, logging, session management, and graceful shutdown, so you can quickly build and extend MCP servers for a variety of clients and use cases.

How to use

Connect your MCP client to the server using the SSE endpoint. You authenticate by passing your API key in the connection URL or via the configured transport. The server maintains sessions for multiple clients, streams keepalive messages to prevent timeouts, and provides a structured way to call tools you define on the server.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

Clone or obtain the project files for the MCP boilerplate, then install dependencies and start the server.

npm install

Create a .env file with the following variables:

PORT=4005
API_KEY=your_api_key

npm run build

npm run start:sse

Additional setup notes

This server uses a centralized configuration with API key protection and keeps logs at configurable levels. You can customize tool definitions and add your own tools to extend MCP capabilities.

Configuration and runtime details

Key runtime settings influence transport behavior and tool execution retries. You can adjust keepalive intervals, retry logic, and log levels to suit your environment.

Security considerations

Example tools

The server includes an example tool named calculator that performs basic arithmetic operations.

// Example tool definition (conceptual)
{
  name: "calculator",
  description: "Performs add, subtract, multiply, divide",
  inputSchema: { type: "object", properties: {}, required: [] },
  handler: async () => {
    // implementation
  },
}

Troubleshooting SSE timeouts

If you encounter body timeout errors, try increasing stability by adjusting keepalive and ping settings, and ensure proxies do not terminate long-held connections.

Notes on extensibility

You can extend the boilerplate by adding custom tools and wiring them into the tool registry. Follow the example structure to create handlers, define input schemas, and register new tools.

Environment variables

Environment variables that you may configure include PORT and API_KEY as shown in the development setup. You can add additional environment variables for your deployment as needed.

Available tools

calculator

Performs basic arithmetic operations (add, subtract, multiply, divide)