MCP server

The cascade, inside your editor.

Drop AdaptivMapr into Cursor or Claude Desktop and the agent can browse 33 templates, match a messy header row and validate a record without an API key — and without a data row leaving your machine beyond column names and a handful of clamped samples.

Add to Cursor Read the quickstart

npx -y @adaptivmapr/mcp-server

tool call

adaptivmapr.match_headers({
  template_id: "patient_demographics_v1",
  headers: ["Vorname", "Nom", "Date de naissance"]
})

result

{
  "template_id": "patient_demographics_v1",
  "matches": [
    { "source_col": "Vorname", "target_field": "first_name",
      "confidence": 1.0, "source": "heuristic" },
    { "source_col": "Nom", "target_field": "last_name",
      "confidence": 1.0, "source": "heuristic" },
    { "source_col": "Date de naissance", "target_field": "date_of_birth",
      "confidence": 1.0, "source": "heuristic" }
  ],
  "unmapped": []
}

→ 3 headers, 3 languages, all resolved on layer 2 · no LLM call

Install

One block of JSON, no key to start.

The server runs straight from npm as a stdio process your editor owns. Nothing is deployed, nothing listens on a port, and the key-less tools answer from the first launch.

Paste the block
Into ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop, or .cursor/mcp.json for Cursor. The deep link above writes the same entry for you.
Restart the client
There is nothing to host and nothing to keep running: the server speaks stdio over a process your editor spawns, and npx fetches the package on first launch.
Add a key only when you need a row
5 of the 10 tools answer with no ADAPTIVMAPR_API_KEY at all. The other 5 say what they need rather than failing, so an evaluator can work the cascade before there is an account.

Configclaude_desktop_config.json · .cursor/mcp.json

{
  "mcpServers": {
    "adaptivmapr": {
      "command": "npx",
      "args": ["-y", "@adaptivmapr/mcp-server"],
      "env": {
        "ADAPTIVMAPR_API_URL": "https://api.adaptivmapr.com",
        "ADAPTIVMAPR_API_KEY": "mp_live_..."
      }
    }
  }
}

Both env values are optional and both are read by name. Drop ADAPTIVMAPR_API_KEY entirely to run key-less. Set it and adaptivmapr.match_headers sends it too, which adds the ranker and the AI layer and bills each map to the key’s workspace wallet. Keep ADAPTIVMAPR_API_URL pinned to the API host, because the apex is not it.

ADAPTIVMAPR_API_KEY
ADAPTIVMAPR_API_URL
ADAPTIVMAPR_MCP_TELEMETRY=1

10 tools, 5 key-less
33 templates across 7 packs
3 guided prompts
4 MCP resources
Schema-only clamp at the edge

Tools

5 tools that need no key at all.

Every one of these is schema-only by construction: column names, at most three sample rows clamped to 80 characters, and nothing else. One of them never opens a socket.

Tool	Calls	What it does
`adaptivmapr.list_templates`	`GET /v1/templates`	The whole catalogue — packs, risk levels, FHIR resources, field counts. Takes no input.
`adaptivmapr.template_schema`	`GET /v1/templates/:id`	One template in full: columns, types, validators, multilingual hints, FHIR mapping.
`adaptivmapr.match_headers`	`POST /v1/match`	The signature tool. Up to 200 headers plus at most 3 sample rows in; ranked mappings with confidence and the layer that resolved each one out. With no key it is anonymous and free: the deterministic layers only. With ADAPTIVMAPR_API_KEY set it sends the key, adds the mapping ranker and the AI layer on what those leave open, and bills each map to that key’s workspace wallet (a 402 means the wallet is empty).
`adaptivmapr.validate_row`	`POST /v1/validate-row`	Run one row against a template’s validators — the same pure functions the Worker runs on commit.
`adaptivmapr.csv_preview`	`no network`	Parse a CSV on your own disk and return its headers plus the first N rows (≤100). Refuses files over 50 MB.

No API key required. With a key configured, adaptivmapr.match_headers sends it: every map then draws the flat per-map fee plus any metered ranker/AI usage from the key’s workspace wallet — including a fully deterministic one that never reached an AI layer. Unset the key to stay on the free deterministic path.

Full-data

5 tools that see an actual row.

These need a valid key and a funded wallet, and PHI routing stays locked until your workspace accepts the BAA/NDA in the app. An explicit PHI ask without an acceptance comes back 403 with a pointer to the settings page — never a silent downgrade.

Tool	Calls	What it does
`adaptivmapr.upload_file`	`POST /v1/uploads`	Upload a file from your disk and get its upload_id and detected columns back. Every tool below starts from that id.
`adaptivmapr.match_full_file`	`POST /v1/uploads/:id/match`	Full-data mapping over a whole upload. Routes to phi-cloud with X-PHI and X-Region so the gateway forces a PHI-eligible, in-region model.
`adaptivmapr.commit_to_webhook`	`POST /v1/uploads/:id/commit`	Finalise an import and stream the mapped rows to your webhook, HMAC-signed with a secret you supply per call. Returns a delivery receipt, never the rows.
`adaptivmapr.commit_to_database`	`POST /v1/uploads/:id/commit`	Write the validated rows into your own database or warehouse through a destination connector you saved in the dashboard. dry_run rehearses the write without sending anything.
`adaptivmapr.transform`	`POST /v1/transform`	One-shot map + validate for a small file (base64, ≤256 KB). The mapped rows come back into the conversation, so keep it for data you may share with the model.

The match and commit tools take the upload_id that adaptivmapr.upload_file returns. Every map draws the flat per-map fee; full-data operations bill the phi-cloud tokens they consume at provider cost × 2 (× 0.5 with your own LLM key) from your prepaid wallet, and a PHI-routed run adds 20% to the whole map charge.

What actually leaves your machine

The clamp is not the client’s job.

An MCP server runs on the reader's laptop, which means they can edit it. So none of the limits below live in it.

Enforced at the HTTP edge

Schema-only limits are applied in every /v1 route that takes sample rows, not in the MCP client. A patched client asking for a fourth row has it clamped away at the API, so a modified client cannot widen the boundary.

One tool never opens a socket

adaptivmapr.csv_preview reads and parses the file on your own disk and returns headers plus rows. There is no request to refuse, because there is no request.

Keys are self-contained

An mp_live_ key is an HMAC-signed payload — verifying one needs no lookup. v1 bearer auth then layers a Supabase revocation check on top and fails CLOSED, so a revoked key stops working even though its signature still checks out.

There is no SDK to install

The MCP server is a thin stdio client over plain HTTPS calls you can paste into a terminal. Nothing vendored, nothing to audit but the requests themselves.

https://api.adaptivmapr.com/v1/templates: the documented host
https://adaptivmapr.com/api/v1/templates: the apex, via /api
https://adaptivmapr.com/v1/templates: 404 — no /api prefix, not the API host

What we store, and for how long →

Beyond tools

Resources and prompts, so the agent can look it up.

MCP is more than a function list. The catalogue is also exposed as readable resources — listable, so a client can enumerate every pack and template — and three guided prompts ship with the server, so an agent can read a template rather than guess at one.

Resources

adaptivmapr://docs/quickstart
The import flow, end to end, as the agent’s reading material.
adaptivmapr://docs/validators
Every validator id and what it checks.
adaptivmapr://packs/{packId}
One pack and its templates, resolved live and cached for an hour.
adaptivmapr://templates/{templateId}
One template definition, resolved live and cached for an hour.

Prompts

adaptivmapr.import_csv
Guided end-to-end import: preview the file, find a template, match headers, present the diff, then optionally commit.
adaptivmapr.design_schema
Turn a natural-language description of a destination shape into an AdaptivMapr template.
adaptivmapr.migrate_from_flatfile
Read an existing Flatfile config and produce the equivalent template registration plus import code.

Ready when you are

Map regulated data — right in your editor.

Install the server, try the 5 key-less tools on a real file, and add a key when you need the 5 that see a row.

Get an API key See pricing →

No free tier · $10 prepaid wallet to start · schema-only is a data-minimization mode, not a tier