@adaptivmapr/mcp-server

MCP server for AdaptivMapr — data adaptation over Model Context Protocol.

This package exposes AdaptivMapr's mapping primitives as MCP tools so a developer in Cursor, Claude Desktop, or any MCP-aware client can drive a data import end-to-end without touching the REST API directly.

• Free, schema-only tools work with no API key — only column headers and up to 3 sample rows ever leave the caller.
• Gated, full-data tools require an AdaptivMapr API key. Full-data LLM cleanup is metered against your plan.

Install

One-shot, no config:

npx -y @adaptivmapr/mcp-server

Claude Desktop / Cursor config

Add to claude_desktop_config.json (Claude Desktop) or your MCP config (Cursor):

{
  "mcpServers": {
    "adaptivmapr": {
      "command": "npx",
      "args": ["-y", "@adaptivmapr/mcp-server"],
      "env": {
        "ADAPTIVMAPR_API_KEY": "am_live_...",
        "PHI_GATEWAY_API_KEY": "phi_live_..."
      }
    }
  }
}

Both env vars are optional. Without them the server still registers the free tools and rejects the gated ones with an upgrade message.

Environment variables

| Variable | Default | Purpose | |---|---|---| | ADAPTIVMAPR_API_URL | https://api.adaptivmapr.com | Override the AdaptivMapr control-plane base URL. | | ADAPTIVMAPR_API_KEY | (unset) | Required for any gated tool. | | PHI_GATEWAY_API_KEY | (unset) | Required for healthcare full-data calls routed through PHI Gateway. | | PHI_GATEWAY_URL | https://api.phi-gateway.dev | Override the PHI Gateway base URL. | | ADAPTIVMAPR_SELFHOSTED_WORKER_URL | (unset) | Required for adaptivmapr.commit_to_database. | | ADAPTIVMAPR_MCP_TELEMETRY | (on) | Set to 0 to disable anonymous telemetry. | | ADAPTIVMAPR_TELEMETRY_URL | https://telemetry.adaptivmapr.com/mcp | Override the telemetry endpoint. |

Tool catalogue

Free (schema-only — no API key required)

| Tool | What it does | |---|---| | adaptivmapr.list_templates | List the pre-built templates (pack, FHIR resource where applicable, risk, languages). | | adaptivmapr.template_schema | Return the full schema (columns, validators, hints) for one template. | | adaptivmapr.match_headers | Match headers + up to 3 sample rows against a template. Hard-capped to 3 rows. | | adaptivmapr.validate_row | Validate one row against a template's per-field validators. | | adaptivmapr.csv_preview | Pure-local Papaparse helper. Returns headers + first N rows of a CSV. 50 MB max. |

Gated (full-data — requires ADAPTIVMAPR_API_KEY)

| Tool | What it does | |---|---| | adaptivmapr.match_full_file | Full-file mapping with LLM cleanup on the long tail. | | adaptivmapr.commit_to_webhook | Commit validated rows from an upload to a customer webhook. | | adaptivmapr.commit_to_database | Commit validated rows via a self-hosted worker. Also requires ADAPTIVMAPR_SELFHOSTED_WORKER_URL. |

Telemetry

Opt-in anonymous install and per-tool invocation counts. The payload contains:

• An anonymous install ID (a UUIDv4 cached at ~/.config/adaptivmapr/mcp-install-id).
• The event name (install or invoke).
• For invoke, the tool name (e.g. adaptivmapr.match_headers).
• The package version and a timestamp.

What is never sent:

• Tool arguments
• Response bodies
• Request headers
• File paths
• Row values
• Header values

The telemetry endpoint is separate from the mapping API, so a network block on telemetry never degrades tool function. Disable entirely with:

ADAPTIVMAPR_MCP_TELEMETRY=0

License

MIT. See LICENSE.

Links

• Documentation: https://adaptivmapr.com/docs
• AdaptivMapr: https://adaptivmapr.com
• Contact: [email protected]