Template MCP Server

You can run an MCP (Model Context Protocol) server to expose tools, resources, and prompts that your team can use locally or over the network. This server supports both a local stdio (CLI) transport and an HTTP transport for web-based clients, making it easy to develop, test, and collaborate on MCP-powered tooling.

How to use

You will interact with your MCP server through a client that connects over stdio or HTTP. Start the server locally to run CLI-style tools and prompts, or run it as an HTTP service so teammates can access it from other machines. Use the built-in tools, resources, and prompts you define to create a productive development environment.

How to install

Prerequisites: you need Node.js and a package manager (npm, yarn, pnpm, or bun) installed on your development machine.

Choose one of the bootstrap methods to create your MCP server project:

# With npx
npx @mcpdotdirect/create-mcp-server

# Or with npm
npm init @mcpdotdirect/mcp-server

Running and developing the server

After setting up your project, install dependencies and start the server with the commands shown below. You can run in stdio mode for CLI tools or in HTTP mode for web-based usage.

# Install dependencies
npm install

# Start the stdio (CLI) server
npm start

# Start the HTTP server
npm run start:http

Development with auto-reload

For a smoother development experience, use the development scripts that enable auto-reload.

# Development mode with stdio
npm run dev

# Development mode with HTTP
npm run dev:http

Connecting to the server from a client

You can connect via two transport methods depending on where your client runs.

• stdio transport (CLI mode): run locally and interact directly. This is ideal for personal tooling and local development.

• HTTP transport (web mode): expose an HTTP endpoint that teammates can access, enabling collaboration across machines.

Transport methods and port configuration

The server supports two transports. The HTTP server defaults to port 3001, and you can override it with the PORT environment variable.

To run the HTTP server on a custom port, set PORT before starting the server.

Testing your server with CLI tools

You can test and inspect the MCP server using dedicated tools.

# Test with mcp-cli
npx fastmcp dev server.js

# Inspect with MCP Inspector
npx fastmcp inspect server.ts

Using environment variables

Customize server behavior by setting environment variables as needed. For example, to change the HTTP port or host binding, set PORT or HOST before starting the server.

Adding custom tools and resources

Extend the MCP server by adding tools, resources, and prompts. The following examples illustrate how to define a simple tool and a prompt.

server.addTool({
  name: "hello_world",
  description: "A simple hello world tool",
  parameters: z.object({
    name: z.string().describe("Name to greet")
  }),
  execute: async (params) => {
    return `Hello, ${params.name}!`;
  }
});

Prompts and resources

You can also add prompts and resources to your MCP server to support common interactions and data retrieval.

server.addPrompt({
  name: "greeting",
  description: "A simple greeting prompt",
  arguments: [
    { name: "name", description: "Name to greet", required: true }
  ],
  load: async ({ name }) => {
    return `Hello, ${name}! How can I help you today?`;
  }
});

Security and best practices

Keep your server updated and constrain access when hosting over HTTP. Use authentication and network controls as appropriate for your environment.

Available tools

hello_world

A simple hello world tool that responds with a greeting using a provided name.

greeting

A simple greeting prompt that asks for a name and returns a friendly message.