MCP Server Starter

A minimal, production-ready starter for building Model Context Protocol servers in TypeScript. One server definition runs two ways: over stdio for local clients, and over streamable HTTP when you deploy it, with optional bearer-token auth.

Features

• Two transports, one definition. Runs over stdio locally (Claude Code, Claude Desktop) and switches to streamable HTTP when PORT is set. Tools live in one place.
• Optional auth for HTTP. A shared bearer token, accepted via the Authorization header or a ?token= query param (some hosted clients can only pass a query param).
• Typed tools. Inputs are validated with zod, so the model gets a clear schema and you get type safety.
• Deploy-ready. Stateless per request, with a Dockerfile included. Runs on any container host.
• Small and readable. A handful of files, no framework, easy to fork.

Quick start

git clone https://github.com/Axis-Data-Labs/mcp-server-starter
cd mcp-server-starter
npm install
cp .env.example .env

Run it locally over stdio:

npm run dev

Connect it to Claude Code

claude mcp add my-server -- npx tsx /absolute/path/to/mcp-server-starter/src/index.ts

Or add it to your client's MCP config:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-server-starter/src/index.ts"]
    }
  }
}

Ask the model to call echo or add to confirm it works.

HTTP mode and deploying

Set PORT to run the streamable HTTP transport instead of stdio:

PORT=3000 MCP_AUTH_TOKEN=your-secret npm start

The server listens on POST /mcp. Point a remote MCP client at https://your-host/mcp and send the token as Authorization: Bearer your-secret (or ?token=your-secret). A Dockerfile is included, and most container platforms set PORT for you, so deploying is usually just pushing the repo.

Adding a tool

1. Create src/tools/<name>.ts and export a register<Name>Tools(server) function.
2. Register tools with server.tool(name, description, zodSchema, handler).
3. Call your register…Tools(server) from src/server.ts.

server.tool(
  "greet",
  "Greet someone by name.",
  { name: z.string().describe("Who to greet") },
  async ({ name }) => ({ content: [{ type: "text", text: `Hello, ${name}` }] }),
);

Project structure

src/
  index.ts        picks the transport (stdio vs HTTP) at startup
  server.ts       builds the server and registers tools
  http.ts         streamable HTTP transport and optional auth
  tools/
    example.ts    example tools, replace with your own

License

MIT. See LICENSE.

Built and maintained by Axis Data Labs.