filiksyos/coin-flip-mcp

🪙 Coin Flip MCP

A simple and lightweight Model Context Protocol (MCP) server that provides a coin flip tool. Randomly generates either "heads" or "tails" when called.

What is this?

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.

Features

✨ Simple - One tool, one purpose
🎲 Truly Random - Uses Math.random() for unbiased coin flips
⚡ Lightweight - Minimal dependencies
🚀 Production Ready - Built with xmcp framework

Installation

1. Clone or download this project
2. Install dependencies:

pnpm install

Quick Start

Development Mode

Start the MCP server with hot reloading:

pnpm dev

This will start the server and watch for changes.

Production Build

Build the project:

pnpm build

Run the built server:

pnpm start

Usage

The server exposes the toss_coin tool via MCP. When called, it returns either:

• heads
• tails

Example Call

Tool: toss_coin
Input: (no parameters needed)
Output: "heads" or "tails"

Project Structure

src/
└── tools/
    └── toss-coin.ts    # The coin flip tool implementation

How It Works

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";

Extending

Want to add more tools? Follow these steps:

1. Create a new .ts file in src/tools/
2. Export schema (tool parameters using Zod)
3. Export metadata (tool name, description, annotations)
4. 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!

Learn More

• xmcp Documentation
• Model Context Protocol