Build your first MCP server for Claude

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
import { z } from 'zod';

function buildServer() {
  const server = new McpServer({ name: 'quickstart-server', version: '1.0.0' }); // the name Claude sees

  // One tool: its name, the description Claude reads to decide when to call it, and its inputs.
  server.registerTool(
    'roll_dice',
    {
      title: 'Roll dice',
      description: 'Roll `count` dice with `sides` sides each. Returns each roll and the total.',
      inputSchema: {
        sides: z.number().int().min(2).max(100).describe('Number of sides per die (2-100)'),
        count: z.number().int().min(1).max(10).default(1).describe('How many dice to roll (1-10)'),
      },
    },
    // Runs when Claude calls the tool. The text you return is what Claude reads.
    async ({ sides, count }) => {
      const rolls = Array.from({ length: count }, () => 1 + Math.floor(Math.random() * sides));
      const total = rolls.reduce((a, b) => a + b, 0);
      return { content: [{ type: 'text', text: `Rolled ${count}d${sides}: [${rolls.join(', ')}] total=${total}` }] };
    },
  );
  return server;
}

// Streamable HTTP: every MCP message arrives as a POST to /mcp. Stateless, so each request gets a fresh server.
const app = createMcpExpressApp(); // Express app with JSON parsing and localhost protection built in
app.post('/mcp', async (req, res) => {
  const server = buildServer();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined }); // undefined = no sessions
  res.on('close', () => { transport.close(); server.close(); });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
const notAllowed = (req, res) => res.status(405).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed.' }, id: null });
app.get('/mcp', notAllowed);
app.delete('/mcp', notAllowed);

const PORT = Number(process.env.PORT ?? 3000);
app.listen(PORT, '127.0.0.1', (err) => { // Express 5 reports a taken port here instead of throwing
  if (err) { console.error(`failed to listen on ${PORT}: ${err.message}`); process.exit(1); }
  console.log(`quickstart-server listening on http://localhost:${PORT}/mcp`);
});