MCP Server Boilerplate: AI-First Tooling & Env Config Simplified

Key Features of MCP Server Boilerplate: AI-First Tooling & Env Config Simplified?

• Zero-to-Tooling in Minutes: Preconfigured transport layer with StdioServerTransport ensures seamless IDE integration
• Schema-Driven Safety: Zod validation enforces strict input formats (numbers only for addition tool)
• Env Management Made Easy: Demonstrates secure pattern for loading credentials without hardcoding
• Future-Proof Architecture: Modular tool definitions make adding new functions as simple as writing a new handler

Use Cases of MCP Server Boilerplate: AI-First Tooling & Env Config Simplified?

Power users might use this boilerplate to:

• Create custom linters that instantly check code quality during editing
• Build API query tools that auto-fetch real-time data during code writing
• Implement security gateways that validate credentials before sensitive operations
• Set up environment-specific tooling that adapts to different deployment stages

FAQ from MCP Server Boilerplate: AI-First Tooling & Env Config Simplified?

Q: Does this work with older Node versions?
A: Nope, Node 20+ only - we prioritize modern ESM features for better maintainability

Q: Can I add more tools later?
A: Absolutely! The boilerplate's structure makes adding new tools as simple as writing a few TypeScript interfaces and handler functions

Q: Is the API key really secure?
A: The example uses env vars, but we recommend using secret managers like Vault in production setups for enterprise-grade protection

Q: What happens if my tool errors?
A: Errors are gracefully propagated back to the IDE, with stack traces available for debugging - no silent failures here

MCP Server Boilerplate

Overview

MCP (Model Context Protocol) is a framework that allows you to integrate custom tools into AI-assisted development environments—such as Cursor AI. MCP servers expose functionality (like data retrieval or code analysis) so that an LLM-based IDE can call these tools on demand. Learn more about MCP in the Model Context Protocol Introduction.

This project demonstrates an MCP server boilerplate that provides two basic tools. One tool, add , accepts two numbers and returns their sum, while the other, getApiKey , retrieves the API key from the environment (via the API_KEY variable).

Requirements

• Node.js: Version 20 or higher is required.

Features

• MCP Integration: Exposes tool functionality to LLM-based IDEs.
• Addition Tool: Accepts two numeric parameters and returns their sum.
• Env Var Retrieval: Demonstrates how to load an example environment variable from the configuration file.
• Input Validation: Uses Zod for schema validation.
• Standard I/O Transport: Connects via StdioServerTransport for integration with development environments.

Installation

1. Clone the Repository

   git clone

cd <repository_directory>

2. Install Dependencies

You can install the project dependencies in one of two ways:

Option 1: Install using the existingpackage.json

Simply run:

    npm install

Option 2: Install dependencies manually

If you prefer, delete the existing package.json and install the required packages manually:

    npm install @modelcontextprotocol/sdk @coinpaprika/api-nodejs-client zod

Then, update the newly generated package.json file to include the following line, which enables ES Modules:

    "type": "module"

Integrating with Cursor AI

This project includes a ./cursor subdirectory that contains an mcp.json file for configuring the MCP server. Cursor AI uses this file to automatically discover and launch your MCP server. Open the file and update the fields as follows:

The ./cursor/mcp.json Structure

Below is the full JSON structure of the configuration file:

{
  "mcpServers": {
    "MCP Server Boilerplate": {
      "command": "/path/to/node",
      "args": ["/path/to/mcp-server.js"],
      "env": {
        "API_KEY": "abc-1234567890"
      }
    }
  }
}

• mcpServers:
  An object mapping server names to their configuration.

• MCP Server Boilerplate:
  This is the key for your server configuration. You can name it as you like.

• command:
  Specifies the absolute path to your Node.js executable. For example:

  /home/john/.nvm/versions/node/v20.13.1/bin/node
  

• args:
  An array containing the absolute path to your MCP server file. For example:

  ["/home/john/mcp-server-boilerplate/index.js"]
  

• env: (Optional)
  Defines environment variables for your MCP server process. In this example, the API_KEY is set to "abc-1234567890". Adjust this value as needed for your environment.

You can verify the absolute path to your Node.js executable by running which node in your terminal.

Optional: Global Configuration

If desired, you can move the mcp.json file from the ./cursor subdirectory to your global Cursor AI configuration directory located at ~/.cursor. This allows Cursor AI to recognize your MCP server configuration globally.

Using the MCP Tool in Cursor Composer (Agent Mode)

With the MCP server integrated into Cursor AI and with Agent mode enabled in Cursor Composer, simply use a natural language prompt like:

add 3 and 5

or

what is my API key?

The AI agent will infer the available add or getApiKey tool from your MCP server and execute it accordingly.

Code Overview

The project comprises the following key parts:

• MCP Server Initialization:
  The MCP server is instantiated using McpServer from the MCP SDK and connected via StdioServerTransport.

• Tool Definitions:

  • add:

Defined with a Zod schema that accepts two numbers (a and b) and returns their sum as text.
* getApiKey:
Retrieves the API key from the environment variable API_KEY and returns it as text.

What is MCP?

Model Context Protocol (MCP) provides a standardized approach to integrate custom tools into AI-assisted development environments. With MCP, you can define tools that perform specific tasks—such as retrieving external data, validating code, or enforcing coding standards—and the AI assistant in your IDE can call these tools automatically based on context. This helps improve developer productivity, ensures consistent quality, and streamlines workflows.

Reference

Use Your Own MCP on Cursor in 5 Minutes

License

This project is licensed under the MIT License.