A simple and lightweight Model Context Protocol (MCP) server that provides a coin flip tool. Randomly generates either "heads" or "tails" when called.
This is an MCP server built with xmcp that exposes a single tool: toss_coin. It's a minimal example of how to build MCP servers with TypeScript.
✨ Simple - One tool, one purpose
🎲 Truly Random - Uses Math.random() for unbiased coin flips
⚡ Lightweight - Minimal dependencies
🚀 Production Ready - Built with xmcp framework
- Clone or download this project
- Install dependencies:
pnpm installStart the MCP server with hot reloading:
pnpm devThis will start the server and watch for changes.
Build the project:
pnpm buildRun the built server:
pnpm startThe server exposes the toss_coin tool via MCP. When called, it returns either:
headstails
Tool: toss_coin
Input: (no parameters needed)
Output: "heads" or "tails"
src/
└── tools/
└── toss-coin.ts # The coin flip tool implementation
The toss_coin tool uses JavaScript's Math.random() to generate a random number between 0 and 1. If the number is less than 0.5, it returns "tails", otherwise "heads". This gives a fair 50/50 distribution.
const result = Math.random() < 0.5 ? "heads" : "tails";Want to add more tools? Follow these steps:
- Create a new
.tsfile insrc/tools/ - Export
schema(tool parameters using Zod) - Export
metadata(tool name, description, annotations) - Export a default function that implements the tool
Example:
import { type InferSchema } from "xmcp";
export const schema = {
sides: z.number().describe("Number of sides on the die"),
};
export const metadata = {
name: "roll_die",
description: "Roll a die",
};
export default async function rollDie({ sides }: InferSchema<typeof schema>) {
const result = Math.floor(Math.random() * sides) + 1;
return {
content: [{ type: "text", text: String(result) }],
};
}The tool will be automatically discovered by xmcp through file-system routing!