home / mcp / boilerplate mcp server

Boilerplate MCP Server

A production-ready MCP server foundation with dual transport, IP geolocation example, and comprehensive tooling.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "aashari-boilerplate-mcp-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "PORT": "3000",
        "DEBUG": "false",
        "NODE_ENV": "development",
        "TRANSPORT_MODE": "http",
        "IPAPI_API_TOKEN": "your_token_here"
      }
    }
  }
}

You deploy a production-ready MCP server foundation that lets an AI assistant securely access external APIs and data sources through a clean, layered TypeScript implementation. It supports both local, stdin/stdout interactions and HTTP-based transports, with strong typing, token-efficient output, and built-in tooling for testing, logging, and error handling.

How to use

Connect your AI assistant to the MCP server using either the STDIO transport for local tooling or the HTTP transport for web-based integrations. The STDIO mode communicates via JSON-RPC over stdin/stdout, while the HTTP mode exposes an MCP endpoint you can query over HTTP. Use the available tools and resources to fetch data, run lookups, and compose responses in a compact TOON format by default or in JSON when you explicitly request it.

How to install

Prerequisites: Node.js 18.x or newer and Git.

Step by step setup and run flow:

# Clone the project
git clone https://github.com/aashari/boilerplate-mcp-server.git
cd boilerplate-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in STDIO transport (local AI assistants)
TRANSPORT_MODE=stdio node dist/index.js

# Run in HTTP transport (web integrations)
TRANSPORT_MODE=http PORT=3000 node dist/index.js

Configuration and startup notes

Core environment variables you can set to customize behavior include TRANSPORT_MODE, PORT, DEBUG, and NODE_ENV. The IP API token can be provided via IPAPI_API_TOKEN for extended data from the external API.

If you need debugging or verbose logs, enable DEBUG=true. Raw responses larger than 40,000 characters are logged to a dedicated directory for later inspection: /tmp/mcp/<project-name> with filenames that include a timestamp and random suffix.

MCP transport and endpoints overview

Two transport modes are supported to connect with AI assistants and web clients.

STDIO Transport: JSON-RPC over stdin/stdout for local assistants like Claude Desktop or Cursor.

HTTP Transport: Streamable HTTP with Server-Sent Events (SSE) that serves the MCP endpoint at /mcp. Health checks and utilities are available at the root and /mcp endpoints.

IP address example quick start

An end-to-end IP geolocation example demonstrates all layers: CLI commands, MCP tools, and resources for IP lookups. You can run current IP lookups, specific IPs, or filtered views using JMESPath.

Available tools

ip_get_details

IP geolocation lookup tool for AI assistants. Retrieves current or specified IP details with optional extended data and JMESPath filtering.