# Humanform MCP server

Stdio MCP server that exposes Humanform API tools to Claude Desktop, Cursor, and other MCP clients.

## Setup

1. Install (optional if you use `npx` in your MCP config):

```bash
npm install @humanform/mcp
```

2. Set your API key from the [Humanform dashboard](https://dashboard.humanform.app):

```bash
export HUMANFORM_API_KEY="hf_live_..."
```

Optional: override the API base URL (defaults to `https://api.humanform.app`):

```bash
export HUMANFORM_API_URL="https://api.humanform.app"
```

3. Add to your MCP client config (Cursor example):

```json
{
  "mcpServers": {
    "humanform": {
      "command": "npx",
      "args": ["-y", "@humanform/mcp"],
      "env": {
        "HUMANFORM_API_KEY": "hf_live_..."
      }
    }
  }
}
```

If you installed globally or locally, you can use `"command": "humanform-mcp"` instead of `npx`.

## Tools

| Tool | API | Description |
|------|-----|-------------|
| `predict_measurement` | `POST /v1/predict` | Forward lookup: percentile → measurement value |
| `percentile_lookup` | `POST /v1/percentile-lookup` | Reverse lookup: measured value → percentile |
| `list_measurements` | `GET /v1/public/measurements` | All supported measurement names and body groups |
| `list_countries` | `GET /v1/countries` | Supported country codes and labels |

API errors (401, 402, 404, 422, 429, etc.) are returned as MCP tool errors with the original `error` and `message` fields from the API.

## Manual testing with MCP Inspector

```bash
HUMANFORM_API_KEY="hf_live_..." npx @modelcontextprotocol/inspector npx -y @humanform/mcp
```

Suggested checks:

- `list_measurements` and `list_countries` (no credit cost)
- `predict_measurement` with valid inputs (e.g. Stature, Male, 30, 50, US, cm)
- `percentile_lookup` with a measured value (e.g. PoplitealHeight, Female, 34, US, cm, 43.1)
- Invalid API key (expect 401)
- Unknown measurement name (expect MCP input validation or API validation_error)
- Free tier exhausted (expect 402 free_tier_exhausted if applicable)

## Local development

For contributors working in the [humanform-api](https://github.com/dougkilby/humanform-api) monorepo:

```bash
pnpm --filter @humanform/mcp build
pnpm --filter @humanform/mcp test:smoke
```

Smoke test and MCP Inspector against a local build:

```bash
pnpm --filter @humanform/mcp build
HUMANFORM_API_KEY="hf_live_..." pnpm --filter @humanform/mcp test:smoke
HUMANFORM_API_KEY="hf_live_..." npx @modelcontextprotocol/inspector node apps/mcp/dist/index.js
```