MCP Starter Server

You can build an MCP server to connect AI models with data sources and tools using a minimal, production‑ready TypeScript starter. This server follows the Model Context Protocol, enabling you to expose tools, resources, and prompts that an AI client can discover and invoke through standard transports like stdio or HTTP.

How to use

You run your MCP server from your development or production environment and connect to it with an MCP client. Start your server in the transport mode you prefer, then load your tools and resources from the client. The server supports auto-loading of modules placed in the designated directories, so you can add new capabilities without editing the core startup code. Use the MCP Inspector during development to test tools, resources, and prompts in an interactive UI.

How to install

Prerequisites: ensure you have Node.js version 20.11.0 or higher installed, along with npm or yarn.

Install steps take you from cloning or using the starter as a template to building and starting your server.

# Install dependencies and build
npm install
npm run build

# Optional: run tests
npm test

# Start in stdio mode (local development)
npm run serve:stdio

# Start in HTTP mode (web deployments)
npm run serve:http

Configuration and transport modes

This server supports two transport modes: stdio (default) and HTTP (SSE + JSON‑RPC). The HTTP endpoints are exposed on port 3000 by default and provide both an SSE endpoint and a JSON‑RPC endpoint at the same path.

Environment variables you can set to control behavior include STARTER_TRANSPORT, PORT, and CORS_ORIGIN.

Example startup commands and environment details are shown in the sections below.

Additional sections

Project structure and how auto-loading works are designed so you can add tools, resources, and prompts by simply placing files in their respective directories. The server will automatically discover and register these modules on startup.

Tools you can use or extend

The starter includes example tool implementations to demonstrate how to expose actions to the AI. You can add new tools by creating a file under src/tools and registering it with the MCP server.

Testing with MCP Inspector

The MCP Inspector provides an interactive UI to test your server. Build the server and then run the inspector to connect and experiment with tools, resources, and prompts.

Configuration samples

{
  "servers": {
    "starter-http": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "name": "starter_http",
      "args": []
    },
    "starter-stdio": {
      "type": "stdio",
      "name": "starter_stdio",
      "command": "node",
      "args": ["build/index.js"]
    }
  }
}

Commands

You can use the following commands to build, inspect, and test your server.

npm run build
npm run inspect
npm test

Security and notes

Keep your environment secure by using absolute paths in client configurations and ensuring your HTTP server is properly restricted in production. Use the MCP Inspector during development to validate behavior before exposing endpoints publicly.

Troubleshooting

If you encounter module resolution errors, ensure you have built the project before starting the server. If the server fails to load tools, verify that the module exports match the expected interface and that auto-loading discovers modules in the correct directories.

Available tools

echo

Example tool that echoes a message back to the user to demonstrate tool invocation and response formatting

calculate

Example tool that performs basic arithmetic operations (add, subtract, multiply, divide) with type‑checked arguments