Flip-a-Coin MCP

A small, open-source-friendly Model Context Protocol (MCP) server that gives compatible AI clients one tool: flip_coin.

The tool performs a fair virtual coin flip and returns either heads or tails. It can be tested locally with MCP Inspector or connected to ChatGPT as a developer-mode app.

What it provides

• A Streamable HTTP MCP endpoint at /mcp
• A health endpoint at /
• A single zero-argument tool named flip_coin
• Human-readable text and structured JSON output
• Configurable port through the PORT environment variable

Example tool response:

{
  "content": [
    {
      "type": "text",
      "text": "The coin landed on heads."
    }
  ],
  "structuredContent": {
    "result": "heads"
  }
}

Requirements

Before starting, install:

• Node.js 18 or newer
• npm, which is included with Node.js
• Optional: ngrok for connecting a local server to ChatGPT

Install

Clone or download this repository, then open a terminal in the project directory.

npm install

Start the server

npm start

The default MCP endpoint is:

http://localhost:8787/mcp

You should see:

Flip-a-Coin MCP listening at http://localhost:8787/mcp

To use a different port:

PORT=3000 npm start

Keep this terminal open while testing or using the server.

Verify the health endpoint

Open http://localhost:8787 in a browser or run:

curl http://localhost:8787/

Expected response:

Flip-a-Coin MCP server is running.

Test with MCP Inspector

Keep the server running and open a second terminal in the project directory:

npm run inspect

In MCP Inspector:

1. Connect to http://localhost:8787/mcp using Streamable HTTP.
2. Open Tools.
3. Select flip_coin.
4. Click Run Tool.
5. Confirm the result is heads or tails.

Connect it to ChatGPT

ChatGPT must be able to reach the MCP server over HTTPS. localhost and 127.0.0.1 are only available on your computer and cannot be entered as the ChatGPT MCP URL.

1. Start the MCP server

In the first terminal:

npm start

2. Create a public HTTPS tunnel

In a second terminal:

ngrok http 8787

ngrok will display a forwarding URL resembling:

https://example-subdomain.ngrok-free.app

The MCP URL is that forwarding URL followed by /mcp:

https://example-subdomain.ngrok-free.app/mcp

http://127.0.0.1:4040 is ngrok's local inspection dashboard. It is not the URL to enter in ChatGPT.

You can verify the tunnel by opening the forwarding URL without /mcp in a browser. It should display the server health message.

3. Enable ChatGPT developer mode

1. Open ChatGPT.
2. Open Settings → Security and login.
3. Turn on Developer mode.

If the option is unavailable in a managed workspace, ask the workspace administrator to enable developer mode.

4. Create the ChatGPT app

1. Open Settings → Plugins, or visit chatgpt.com/plugins.
2. Select the plus button to create a developer-mode app.
3. Enter the following information:
   • Name: Flip a Coin
   • Description: Flips a fair virtual coin when the user asks to flip or toss a coin.
   • MCP server URL: your complete ngrok URL ending in /mcp
   • Authentication: none
4. Select Create.
5. Confirm ChatGPT discovers the flip_coin tool.

See OpenAI's current Connect from ChatGPT guide if the interface differs.

5. Test it in a conversation

1. Start a new ChatGPT conversation.
2. Click + → More near the message composer.
3. Select Flip a Coin.
4. Try one of these prompts:

Flip a coin using the Flip a Coin app.

Toss a coin for me.

Choose between pizza and tacos. Heads is pizza and tails is tacos.

Both npm start and ngrok must remain running. Free ngrok URLs may change after ngrok restarts; if that happens, update the MCP URL in ChatGPT.

Test with curl

Initialize the MCP server:

curl -sS http://localhost:8787/mcp \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "manual-test",
        "version": "1.0.0"
      }
    }
  }'

List the available tools:

curl -sS http://localhost:8787/mcp \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Call flip_coin:

curl -sS http://localhost:8787/mcp \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "flip_coin",
      "arguments": {}
    }
  }'

Project structure

.
├── README.md
├── package-lock.json
├── package.json
└── server.js

• server.js defines the MCP tool and HTTP server.
• package.json contains the runtime dependencies and npm scripts.

Troubleshooting

ChatGPT cannot connect

• Confirm npm start is still running.
• Confirm ngrok is still running.
• Use the HTTPS forwarding URL, not localhost or 127.0.0.1:4040.
• Ensure the URL ends with /mcp.
• Open the forwarding URL without /mcp and confirm the health message appears.
• Refresh the developer-mode app after changing tool metadata.

Port 8787 is already in use

Stop the process already using the port or choose another port:

PORT=3000 npm start
ngrok http 3000

The server exits on the first MCP request

Run npm install to ensure the locked dependency versions are installed, then restart the server. If it still exits, inspect the terminal running npm start for the complete error message.

MCP Inspector does not open

The first npm run inspect may download MCP Inspector through npx. Confirm the machine has internet access and try again.

Production considerations

The ngrok workflow is intended for development. For a persistent installation:

• Deploy the server to a host that supports a continuously running Node.js HTTP process.
• Use a stable HTTPS domain.
• Add request logging, rate limiting, monitoring, and graceful shutdown handling.
• Add authentication if the endpoint should not be public.
• Keep dependencies updated and test tool discovery after upgrades.

For private deployments, OpenAI also documents Secure MCP Tunnel, which lets supported OpenAI products reach a private MCP server without opening inbound firewall ports.

Contributing

Issues and pull requests are welcome. Please keep changes small, document user-visible behavior, and verify the server through MCP Inspector or the curl examples before submitting.

License

Add a LICENSE file before publishing the repository and update this section with the selected open-source license. MIT and Apache-2.0 are common choices for small developer tools.