🤖 AI & API Documentation

🔌 REST API

We provide a public REST API for calculating egg boil times. It's perfect for custom applications or integrating with AI assistants like ChatGPT via Custom Actions.

Endpoint

POST https://boilmyeggs.com/api/calculate

Request Headers

• Content-Type: application/json

Request Body

{
  "altitudeMeters": 0,
  "eggSize": "large",
  "doneness": "jammy",
  "startingTempC": 4,
  "waterStart": "hot",
  "eggCount": 4
}

Parameters

Success Response (200 OK)

{
  "success": true,
  "data": {
    "seconds": 420,
    "boilingPointC": 100,
    "doneness": "jammy",
    "warnings": [],
    "guidance": [
      "Add eggs to boiling water and start the timer",
      "Leave the lid off while cooking",
      "For easy peeling, immediately transfer eggs to ice water for at least 5 minutes"
    ]
  }
}

🧠 Model Context Protocol (MCP)

Our MCP server allows AI assistants to natively understand and calculate egg boiling times. It exposes the calculate_boil_time tool, which uses the exact same parameters as the REST API.

Important: The tool is designed to prompt the user for their altitude if it's not provided, ensuring accurate calculations rather than assuming sea level.

Server URL (SSE)

https://boilmyeggs.com/mcp

🛠️ Integration Guides

Claude Desktop (MCP)

To add BoilMyEggs to Claude Desktop, edit your claude_desktop_config.json file and add the following configuration. Since our MCP server is hosted via SSE, you can use a simple proxy script or an SSE client, but the easiest way is to use the @modelcontextprotocol/client if you have a local wrapper, or use an SSE-to-stdio bridge.

Note: Claude Desktop currently primarily supports stdio connections. You may need an SSE-to-stdio bridge like mcp-proxy to connect to our hosted SSE endpoint.

{
  "mcpServers": {
    "boilmyeggs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/proxy",
        "https://boilmyeggs.com/mcp"
      ]
    }
  }
}

Cursor (MCP)

You can easily add our MCP server to Cursor to help you build egg-related applications:

1. Open Cursor Settings (gear icon).
2. Navigate to Features > MCP.
3. Click + Add New MCP Server.
4. Set the Name to BoilMyEggs.
5. Set the Type to SSE.
6. Set the URL to https://boilmyeggs.com/mcp.
7. Click Save.

ChatGPT Custom Actions (REST)

To create a Custom GPT that can calculate egg boiling times:

1. Go to the GPT Builder and click Create new action.
2. Paste the following OpenAPI schema:

openapi: 3.1.0
info:
  title: BoilMyEggs API
  version: 1.0.0
servers:
  - url: https://boilmyeggs.com/api
paths:
  /calculate:
    post:
      summary: Calculate egg boil time
      operationId: calculateBoilTime
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - altitudeMeters
                - eggSize
                - doneness
                - startingTempC
                - waterStart
                - eggCount
              properties:
                altitudeMeters:
                  type: number
                  description: Altitude in meters (0-5500)
                eggSize:
                  type: string
                  enum: [medium, large, extraLarge]
                doneness:
                  type: string
                  enum: [soft, jammy, hard]
                startingTempC:
                  type: number
                  description: Starting temp in Celsius (4-30)
                waterStart:
                  type: string
                  enum: [hot, cold]
                eggCount:
                  type: number
                  description: Number of eggs (1-24)
      responses:
        '200':
          description: Successful calculation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      seconds:
                        type: number
                      boilingPointC:
                        type: number
                      doneness:
                        type: string
                      warnings:
                        type: array
                        items:
                          type: string
                      guidance:
                        type: array
                        items:
                          type: string