Posha API MCP Server

MCP (Model Context Protocol) server that provides AI assistants with read-only access to the Posha API. Supports 17 tools covering all 48 endpoints across 17 resources.

Quick Start

cd resource-api-mcp
npm install
npm run build

Auto-proxy / curated coverage test

Builds TypeScript, loads resource metadata from the API (when reachable), optionally fetches OpenAPI, and asserts curated COVERED_ENDPOINTS stay aligned with the auto-proxy allowlist.

export RESOURCE_API_BASE_URL="http://localhost:8080/servicekit/api/resource/v1"
export RESOURCE_API_KEY="your-key"
npm run test:auto-proxy

The script is src/__tests__/auto-proxy-tools.test.mjs. Without a reachable API, metadata/OpenAPI steps may be skipped or partial; some assertions depend on live metadata (e.g. slug names).

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | RESOURCE_API_BASE_URL | Yes | — | Posha API base URL (e.g. http://localhost:8080/servicekit/api/resource/v1) | | RESOURCE_API_KEY | Yes | — | API key for X-API-Key header | | MCP_TRANSPORT | No | stdio | Transport: stdio or sse | | MCP_PORT | No | 3001 | SSE server port (only when MCP_TRANSPORT=sse) |

Setup

Install via npm

npm install -g posha-api-mcp

Cursor

Add to your Cursor MCP config file (mcp.json, global or project-level). The server name (posha-api below) is arbitrary.

{
  "mcpServers": {
    "posha-api": {
      "command": "npx",
      "args": ["-y", "posha-api-mcp"],
      "env": {
        "RESOURCE_API_BASE_URL": "https://your-api-host/servicekit/api/resource/v1",
        "RESOURCE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Cursor (local checkout)

If you’re developing this MCP server locally, point Cursor at the built dist/index.js entrypoint instead of using npx:

{
  "mcpServers": {
    "posha-api": {
      "command": "node",
      "args": ["/absolute/path/to/resource-api-mcp/dist/index.js"],
      "env": {
        "RESOURCE_API_BASE_URL": "http://localhost:8080/servicekit/api/resource/v1",
        "RESOURCE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Cursor (SSE transport)

This server supports SSE mode. In Cursor, you can still launch it with stdio config and set MCP_TRANSPORT=sse + MCP_PORT, or run it separately (e.g. Docker) and connect to the SSE URL (depending on your client’s MCP support).

{
  "mcpServers": {
    "posha-api": {
      "command": "npx",
      "args": ["-y", "posha-api-mcp@latest"],
      "env": {
        "RESOURCE_API_BASE_URL": "http://localhost:8080/servicekit/api/resource/v1",
        "RESOURCE_API_KEY": "<your-api-key>",
        "MCP_TRANSPORT": "sse",
        "MCP_PORT": "3001"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "posha-api": {
      "command": "npx",
      "args": ["-y", "posha-api-mcp"],
      "env": {
        "RESOURCE_API_BASE_URL": "https://your-api-host/servicekit/api/resource/v1",
        "RESOURCE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Claude Code

claude mcp add posha-api -- npx -y posha-api-mcp

Then set environment variables in your shell or .env file.

Available Tools

Generic Resource Tools

| Tool | Description | |------|-------------| | list_available_resources | Lists all 17 resource types with filterable fields, operators, and sort options | | get_resource | Get any resource by ID (user, session, recipe, machine, etc.) | | query_resources | Query any resource with filters, sorting, pagination, and projection. Metadata slugs may use underscores; URLs are normalized to kebab-case. resourceType images uses v2 POST /api/resource/v2/images/query (same backing API as query_images_v2). |

Recipe Macros Tools

| Tool | Description | |------|-------------| | get_recipe_macros | Fetch all macro ingredients for a recipe — flat macroIngredients[] plus the default variant of each ingredientBlocks[], merged into a single tagged list (source: "macro" \| "block"). Hits GET /recipes/{id}/macros. | | resolve_recipe_macros | Same as get_recipe_macros but accepts selections: [{ingredientId, prepStyle}, ...] to override block defaults. Unmatched selections come back as warnings[] entries with reason: "no_matching_variant". Hits POST /recipes/{id}/macros/resolve. |

Session Tools

| Tool | Description | |------|-------------| | get_session_feedback | Get feedback for a cooking session | | get_session_customisations | Get pre-cooking customisations | | get_session_metadata | Get session timing and step metadata | | query_session_logs | Query session log entries (logs, images, or instructions) |

Image Tools

| Tool | Description | |------|-------------| | list_session_images | List all images for a session | | get_session_instruction_images | Get images for a specific instruction | | get_session_image_detail | Get full metadata for an image | | get_session_macro_images | List images with macro/liquid ingredient state at capture time | | download_session_image | Download image to disk and/or render inline, with source control (auto/high-res) | | list_high_res_images | List all high-res image filenames for a session from S3 | | batch_download_images | Batch download images for one or more sessions with filtering (all/instruction/high-res) | | query_images_v2 | Cross-session image query via POST /api/resource/v2/images/query (flat images collection; optional startTime / endTime helpers) |

Machine Tools

| Tool | Description | |------|-------------| | get_machine_storage | Get machine on-device storage snapshot | | get_machine_details | Get machine users and/or crash dump files |

Query Examples

Find a user by email

Use get_resource with resourceType "users" and id "[email protected]"

Query recent sessions for a user

Use query_resources with resourceType "sessions", filter by cookedBy.uid equals "<uid>",
sort by createdOn desc, limit 10

Fetch all macro ingredients for a recipe

Use get_recipe_macros for the default merged macro list:

Use get_recipe_macros with recipeId "6644b04a2e9e5f0018033dea"

For variant overrides, use resolve_recipe_macros:

Use resolve_recipe_macros with recipeId "6644b04a2e9e5f0018033dea" and selections
[{ingredientId: "6160123bb03528001806f9bd", prepStyle: "STRIPS- Boneless Chicken Breast"}]

Search images across sessions

Use query_images_v2 or query_resources with resourceType images (both call v2 POST /api/resource/v2/images/query):

Use query_images_v2 with startTime "2026-03-01T00:00:00Z", endTime "2026-03-31T00:00:00Z",
and filters for machineId, sessionId, etc. as needed.

Session-scoped lists/downloads use list_session_images, download_session_image, etc. (GET under /api/resource/v2/sessions/.../images/...).

AWS Deployment (SSE mode)

Build and deploy the Docker image:

docker build -t posha-api-mcp .
docker run -p 3001:3001 \
  -e RESOURCE_API_BASE_URL=http://resource-api:8080/servicekit/api/resource/v1 \
  -e RESOURCE_API_KEY=your-key \
  posha-api-mcp

Clients connect via http://<host>:3001/sse.

Health check: GET http://<host>:3001/health