# Flip-a-Coin MCP

A small, open-source-friendly [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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:

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

## Requirements

Before starting, install:

- [Node.js](https://nodejs.org/) 18 or newer
- npm, which is included with Node.js
- Optional: [ngrok](https://ngrok.com/download) for connecting a local server to ChatGPT

## Install

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

```bash
npm install
```

## Start the server

```bash
npm start
```

The default MCP endpoint is:

```text
http://localhost:8787/mcp
```

You should see:

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

To use a different port:

```bash
PORT=3000 npm start
```

Keep this terminal open while testing or using the server.

## Verify the health endpoint

Open [http://localhost:8787](http://localhost:8787) in a browser or run:

```bash
curl http://localhost:8787/
```

Expected response:

```text
Flip-a-Coin MCP server is running.
```

## Test with MCP Inspector

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

```bash
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:

```bash
npm start
```

### 2. Create a public HTTPS tunnel

In a second terminal:

```bash
ngrok http 8787
```

ngrok will display a forwarding URL resembling:

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

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

```text
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](https://chatgpt.com/).
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](https://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](https://developers.openai.com/apps-sdk/deploy/connect-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:

```text
Flip a coin using the Flip a Coin app.
```

```text
Toss a coin for me.
```

```text
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:

```bash
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:

```bash
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`:

```bash
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

```text
.
├── 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:

```bash
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](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels), 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.