{
  "openapi": "3.1.0",
  "info": {
    "title": "Macropass MCP endpoint",
    "version": "0.1.0",
    "summary": "The public integration surface of Macropass, an AI macro tracker by Geometry.",
    "description": "Macropass exposes one public endpoint: a Model Context Protocol server (JSON-RPC 2.0 over HTTPS) at https://auth.macropass.app/mcp. Connected assistants call nine tools to log and read meals and weigh-ins in the user's diary; the tool schemas are published in function-calling format at https://macropass.app/mcp-tools.json. There is no public REST API: Macropass photo, voice and AI estimation, goals, recipes and export are first-party only. Authentication is OAuth 2.1 with PKCE and dynamic client registration; scopes are macropass.read, macropass.write and macropass.history.read.",
    "contact": { "name": "Macropass support", "email": "support@macropass.app", "url": "https://macropass.app/support" },
    "termsOfService": "https://macropass.app/terms"
  },
  "externalDocs": { "description": "Human-readable MCP tools reference", "url": "https://macropass.app/claude-chatgpt/tools" },
  "servers": [{ "url": "https://auth.macropass.app", "description": "Production relay (OAuth issuer and MCP server)" }],
  "security": [{ "macropassOAuth": ["macropass.read"] }],
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "mcpCall",
        "summary": "MCP JSON-RPC endpoint",
        "description": "Accepts one JSON-RPC 2.0 request. Methods: initialize, ping, tools/list, tools/call. tools/list returns the nine external tools with their JSON Schemas; tools/call invokes one by name. Notifications (requests without an id) are acknowledged with an empty 202.",
        "security": [{ "macropassOAuth": ["macropass.read", "macropass.write", "macropass.history.read"] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": {
            "toolsList": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } },
            "logMeal": { "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "macropass_log_meal", "arguments": { "name": "Scrambled eggs and sourdough", "kcal": 390, "protein_g": 18, "carbs_g": 28, "fat_g": 22, "fiber_g": 2, "sugar_g": 2, "items": [{ "name": "Eggs", "qty": "2 large", "kcal": 140, "protein_g": 12, "carbs_g": 1, "fat_g": 10, "fiber_g": 0, "sugar_g": 1 }, { "name": "Butter", "qty": "1 tsp", "kcal": 35, "protein_g": 0, "carbs_g": 0, "fat_g": 4, "fiber_g": 0, "sugar_g": 0 }, { "name": "Sourdough", "qty": "1 slice", "kcal": 215, "protein_g": 6, "carbs_g": 27, "fat_g": 8, "fiber_g": 2, "sugar_g": 1 }], "assumptions": ["Butter counted as 1 tsp"], "note": "two eggs scrambled in butter and a slice of sourdough" } } } }
          } } }
        },
        "responses": {
          "200": { "description": "JSON-RPC result or JSON-RPC error object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } },
          "202": { "description": "Notification acknowledged (no body)" },
          "401": { "description": "Missing or invalid bearer token. WWW-Authenticate carries resource_metadata pointing to the RFC 9728 document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } },
          "403": { "description": "Token lacks the scope the tool requires", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": { "operationId": "getAuthorizationServerMetadata", "summary": "RFC 8414 authorization server metadata", "description": "Issuer, authorization, token and registration endpoints, scopes_supported.", "security": [], "responses": { "200": { "description": "Metadata JSON", "content": { "application/json": { "schema": { "type": "object" } } } } } }
    },
    "/.well-known/oauth-protected-resource/mcp": {
      "get": { "operationId": "getProtectedResourceMetadata", "summary": "RFC 9728 protected resource metadata for /mcp", "description": "Declares the resource, its authorization server and scopes_supported.", "security": [], "responses": { "200": { "description": "Metadata JSON", "content": { "application/json": { "schema": { "type": "object" } } } } } }
    }
  },
  "components": {
    "securitySchemes": {
      "macropassOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.1 with PKCE. Clients register dynamically (RFC 7591) at the registration endpoint; the user approves once in the Macropass sign-in page and can revoke in the app.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://auth.macropass.app/oauth/authorize",
            "tokenUrl": "https://auth.macropass.app/oauth/token",
            "refreshUrl": "https://auth.macropass.app/oauth/token",
            "scopes": {
              "macropass.read": "Read today's meals and nutrition totals.",
              "macropass.write": "Log complete meals, correct or delete meals, log or delete weigh-ins.",
              "macropass.history.read": "List and search past meals and weigh-ins."
            }
          }
        }
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "integer" }, { "type": "string" }], "description": "Omit for a notification." },
          "method": { "type": "string", "enum": ["initialize", "ping", "tools/list", "tools/call"] },
          "params": { "type": "object", "description": "For tools/call: { name: <tool name>, arguments: <object matching the tool's inputSchema> }. Tool schemas: https://macropass.app/mcp-tools.json" }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "integer" }, { "type": "string" }, { "type": "null" }] },
          "result": { "type": "object" },
          "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "-32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error, -32402 payment required (no active subscription)." }, "message": { "type": "string" }, "data": {} }, "required": ["code", "message"] }
        }
      },
      "AuthError": {
        "type": "object",
        "properties": { "error": { "type": "string", "example": "invalid_token" }, "error_description": { "type": "string" } }
      }
    }
  }
}