Coin Flip

You can use this MCP server to obtain true-random coin flip results through an easy-to-use tool that supports configurable sides. It demonstrates how to expose a coin-flipping capability via the Model Context Protocol, letting you request outcomes with different numbers of sides and rely on genuine randomness from an external source.

How to use

Connect to the coin_flip MCP server with your client and invoke the flip_coin tool to get randomized results. You can request a standard 2-sided flip to get Heads or Tails, or specify more sides for richer outcomes. For non-standard edge cases, the tool handles 0, 1, and negative sides gracefully. If you choose 3 sides, you’ll receive Heads, Tails, or _. For any n greater than 3, you’ll get It landed on side X.

How to install

Prerequisites: Node.js installed on your machine. You should also have npm (Node Package Manager) available to install dependencies.

Step 1. Install dependencies

npm install

Step 2. Build the server

npm run build

Step 3. For development with auto-rebuild

npm run watch

Configuring your MCP client to connect to this server

To use this server with an MCP client such as Claude Desktop, add the following MCP configuration to your client setup. This config runs the server locally using npx to invoke the package that provides the coin flip MCP server.

{
  "mcpServers": {
    "coin-flip": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-coin-flip"]
    }
  }
}

Debugging tips

Since MCP servers communicate over stdio, debugging can be tricky. Use the MCP Inspector to run and inspect the server during development.

npx @modelcontextprotocol/inspector node build/index.js

Notes on usage and edge cases

• 2 sides: returns Heads or Tails.
• 3 sides: returns Heads, Tails, or _.
• n > 3 sides: returns It landed on side X.
• 0, 1, or negative sides are handled gracefully with a sensible result.

Development and contribution

Contributions are welcome. You can submit changes via a Pull Request after forking the project and implementing improvements or fixes.

License

MIT License

Available tools

flip_coin

Flip a coin with a configurable number of sides. Uses true randomness from random.org and handles edge cases: 0/1/negative sides, 2 sides yield Heads or Tails, 3 sides yield Heads/Tails/_, and more than 3 sides yield It landed on side X.