Use Flip a Coin with AI Assistants

You can ask AI assistants like Claude, ChatGPT, or any agent framework to perform a real, verifiable coin flip on flip-a-coin.com — instead of having the AI invent a random result. The flip is recorded for 30 days at a citable URL anyone can visit.

Quick start — no installation required

If your AI assistant has any way to fetch a URL (web tools, browsing, an HTTP fetcher), you can use the flip-a-coin API today by copy-pasting a prompt. Nothing to install. Try one of these in ChatGPT, Claude, Gemini, Perplexity, or any AI assistant with web/browsing tools enabled:

Simple flip

Use the URL https://flip-a-coin.com/api/flip and tell me whether
the coin came up heads or tails. Include the verify_url in your answer
so I can check it myself.

Decide between two options

I cannot decide between pizza and burger for dinner.
Please flip a fair coin for me by fetching
https://flip-a-coin.com/api/flip?heads=Pizza&tails=Burger
and tell me what came up, with the verify URL.

Multi-flip experiment

Fetch https://flip-a-coin.com/api/flip?n=1000&format=binary
and summarise: how many heads vs tails came up, and how close
to a perfect 50/50 split was the result?

Quick yes / no

Should I email my boss tonight? Flip a coin by visiting
https://flip-a-coin.com/api/flip?coin=fcc-yes-or-no
and report the result with a one-line justification.

These prompts work because the API is plain HTTPS JSON — any modern AI assistant can call it without a plugin. Citing the verify_url in your answer lets the user audit the flip at flip-a-coin.com/flip/<id> for up to 30 days.

Want the AI to call the coin flip automatically every time, without you pasting URLs? Read on for the MCP and GPT Actions integrations below.

For Claude Desktop users

The easiest path. One config change and you’re done.

  1. Install Node.js if you don’t already have it. (nodejs.org; macOS users can also brew install node.)
  2. Open your Claude Desktop config file:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

    If the file doesn’t exist, create it. If it’s empty, start with { "mcpServers": {} }.

  3. Add the flip-a-coin entry inside mcpServers: 
    {
  "mcpServers": {
    "flip-a-coin": {
      "command": "npx",
      "args": ["-y", "flip-a-coin-mcp"]
    }
  }
}

    If you already have other MCP servers, just add the flip-a-coin key alongside them.

  4. Restart Claude Desktop (quit and reopen).
  5. Test it. Start a new chat and say:
    Flip a coin to decide whether I should have pizza or burger tonight.
    Claude should call the tool, perform the flip, and cite a verify_url in its answer.

For Claude Code users

One line:

claude mcp add flip-a-coin -- npx -y flip-a-coin-mcp

For Gemini CLI users

Gemini CLI (Google’s terminal AI tool) also speaks MCP, so the same flip-a-coin-mcp package works there.

  1. Install Gemini CLI: npm install -g @google/gemini-cli (requires Node.js).
  2. Set an API key: get one free at aistudio.google.com/apikey and export it: 
    export GEMINI_API_KEY=AIza...
  3. Add the MCP server to ~/.gemini/settings.json: 
    {
  "mcpServers": {
    "flip-a-coin": {
      "command": "npx",
      "args": ["-y", "flip-a-coin-mcp"]
    }
  }
}
  4. Run it: 
    gemini -p "Flip a coin: pizza or burger?" \
       --allowed-mcp-server-names flip-a-coin

    The --allowed-mcp-server-names flag is needed in non-interactive (-p) mode; in interactive mode MCP servers are auto-enabled.

Heads up: consumer Gemini chat (gemini.google.com) and Gems don’t support third-party MCP yet — only the Gemini CLI does.

For ChatGPT (zero-setup option)

We’ve published a public Custom GPT pre-wired to the flip-a-coin API. Click the link, then chat as usual — no setup, no schema, no install:

Open Coin Flip — Verified Fair in ChatGPT →

Requires any ChatGPT plan that supports Custom GPTs — Go, Plus, Pro, Business, or Enterprise (Custom GPTs are not available on the Free plan).

Sign in to ChatGPT first. The model can chat without signing in, but ChatGPT disables external Actions for anonymous viewers, so the coin-flip API won’t actually run unless you’re logged in.

Test prompts to try:

  • “Flip a coin to decide between pizza and burger.”
  • “Run 1,000 fair flips and tell me how close to 50/50 it landed.”
  • “Help me decide — should I send this email tonight? Yes or no.”
Build your own Custom GPT instead (advanced)

If you want full control — your own GPT under your own builder profile, custom instructions, branding, or a GPT private to your team — you can build one against our public OpenAPI schema.

  1. In the ChatGPT sidebar click Explore GPTs, then the + Create button in the top-right. This opens the GPT editor.
  2. Switch from the Create tab to the Configure tab at the top of the editor.
  3. Fill in Name, Description, and an Instruction such as: 
    When the user asks you to flip a coin, pick between options, or
make a fair binary decision, call the flipCoin action. Always cite
the returned verify_url so the user can independently confirm the
result at flip-a-coin.com.
  4. Scroll to the bottom of the Configure tab and under Actions click Create new action.
  5. In the Schema box, either click Import from URL (if shown) and paste:
    https://flip-a-coin.com/api/openapi.json
    — or paste the JSON contents of that URL directly into the box.
  6. Leave Authentication as None — flip-a-coin’s API is public and unauthenticated.
  7. Click the back arrow to return to the editor, then Save (top-right). Choose your sharing scope.

For developers (any LLM)

If you’re building your own AI app or agent, hit the API directly. Full documentation: flip-a-coin.com/api/.

Complete tool-use example with the Anthropic SDK (Python). The model decides when to call flip_coin, we execute the call, and the model returns a final answer citing the verify_url:

import anthropic, requests

client = anthropic.Anthropic()

TOOLS = [{
  "name": "flip_coin",
  "description": "Flip a real, cryptographically fair coin via flip-a-coin.com. "
                 "Returns heads/tails plus a verify_url that the user can visit.",
  "input_schema": {
    "type": "object",
    "properties": {
      "heads": {"type": "string", "description": "Custom heads label"},
      "tails": {"type": "string", "description": "Custom tails label"},
      "coin":  {"type": "string", "description": "Coin slug (e.g. fcc-yes-or-no, usd-25cent, ccc-bitcoin)"},
      "n":     {"type": "integer", "minimum": 1, "maximum": 100000, "default": 1,
                "description": "Number of flips per call (1-100,000)"},
      "format":{"type": "string", "enum": ["array", "binary"], "default": "array"},
    },
  },
}]

def call_flip(args):
    r = requests.get(
        "https://flip-a-coin.com/api/flip",
        params=args,
        headers={"User-Agent": "MyApp/1.0"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

# 1. First turn: send the user prompt + tools.
messages = [{"role": "user", "content": "Flip a coin to decide: pizza or burger?"}]
resp = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=TOOLS,
    messages=messages,
)

# 2. If the model wants to call the tool, execute it and reply.
while resp.stop_reason == "tool_use":
    tool_calls = [b for b in resp.content if b.type == "tool_use"]
    messages.append({"role": "assistant", "content": resp.content})

    tool_results = []
    for tc in tool_calls:
        if tc.name == "flip_coin":
            result = call_flip(tc.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": tc.id,
                "content": str(result),  # JSON string is fine
            })
    messages.append({"role": "user", "content": tool_results})

    resp = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        tools=TOOLS,
        messages=messages,
    )

# 3. Final assistant turn — the model will cite verify_url.
for block in resp.content:
    if block.type == "text":
        print(block.text)

For higher-throughput agent loops, swap requests.get for an async client (httpx.AsyncClient) and parallelise multiple flips. The API supports up to 60 requests/min and 5,000/day per IP.

For OpenAI Function Calling or LangChain, see the OpenAPI spec at /api/openapi.json.

What you can ask the AI

  • “Flip a coin to decide if I should take the day off.”
  • “Pizza or burger? Flip a coin.”
  • “Run 10,000 fair coin flips and tell me how many were heads.” (The API supports up to n=100,000 in a single call — full parity with the on-site multi-flip.)
  • “Flip a Quarter coin” (calls coin=usd-25cent) or “Flip the California state quarter” (calls coin=usq-california).
  • “Flip a Bitcoin coin — heads is ‘buy’, tails is ‘hold’.” (For entertainment only — not financial advice.)

How to verify a flip

Every flip returns a URL like https://flip-a-coin.com/flip/<id>. Visit it to see the recorded flip — coin design, heads/tails labels, the result, and the exact UTC timestamp the flip was generated. Records are kept for 30 days.

Privacy & conduct

  • No personal data is collected from your conversation. The MCP server only sends the parameters you specify (coin, labels, n) to our API.
  • Our API records a hash of the IP and User-Agent that called it, plus the Referer hostname, for abuse prevention. These records expire with the flip after 30 days.
  • Rate limit: 60 flips per minute and 5,000 flips per day per source IP. Generous for any reasonable use.
  • Use of the API constitutes acceptance of our Terms of Use and Privacy Policy.

Troubleshooting

Claude says it can’t find a tool called flip_coin after I edited the config.
You probably need to fully quit and relaunch Claude Desktop (closing the window isn’t enough on macOS — use Cmd+Q). The MCP servers load only on app start.
It says “npx: command not found.”
You need Node.js (which includes npx) installed and on your PATH.
I get an error rate_limited.
You’ve made more than 60 requests in a minute. Wait 60 seconds and try again. If you hit the daily 5,000 cap, wait 24 hours.
Can I run my own server / self-host?
The flip-a-coin-mcp source release on GitHub is being prepared and will be published once the package stabilizes. In the meantime the npm package is fully functional — flip-a-coin-mcp on npm — and we’ll update this page when the repo is open. If you want early access or have a specific use case, contact us. Please call our public API rather than scraping the site.
I want a higher rate limit for a real product.
Contact us with a brief description and we’ll discuss.

More info

Share this page

Share this link via

Or copy link