Developers & Agents Updated 2026-08-01 View as Markdown

MCP server

nLight.fit runs a remote Model Context Protocol server at POST https://nlight.fit/api/mcp. It lets an AI client you already use — Claude Desktop, Claude Code, Cursor, or anything else that speaks MCP — query your own tracked data, WHOOP metrics, bloodwork and correlations directly.

The tools are the same handlers the in-app coach uses. There is no second implementation, so an answer you get in Cursor is computed exactly the way the answer in the app is.

What you can reach

Sixteen tools, in two groups.

Curated tools are the ten the in-app coach also calls. They return a conclusion the analysis pipeline already reached: a streak, a metric series with statistics, a correlation the nightly engine judged significant. They are small, fast, and hard to misuse.

Warehouse tools are six that exist only over MCP. They return the underlying evidence instead of a verdict — the raw daily feature matrix, the correlation graph as structured edges, the precomputed statistical models — so a client can test a hypothesis the engine never considered. They are deliberately not offered to the in-app coach, because a 365-day by 40-metric matrix dropped into a chat context produces a worse answer than the single precomputed edge it already had.

The tool reference lists all sixteen with full input schemas.

Read-only, and why

Every exposed tool is a query. Nothing reachable over MCP can change your data.

That is enforced in three places rather than assumed. The endpoint requires the read scope. Tools are published from an explicit allowlist, not from "everything the coach can call", so a write tool added for the in-app coach cannot become publicly reachable by merging. And every tool descriptor carries annotations.readOnlyHint: true, which lets a client run any of them without prompting you for confirmation.

Write tools are a separate phase. They will require a token carrying the write scope, which the auth layer already understands but nothing currently grants over this endpoint.

Transport

Stateless JSON-RPC 2.0 over HTTP POST. One message per request, no session, no handshake required, no long-lived stream.

This matters for a practical reason: the older session-based MCP transport needed a connection pinned to a single server instance, which a serverless platform cannot promise. Protocol revision 2026-07-28 removed the handshake and made every message self-contained, which is what allows this to be an ordinary Vercel function rather than a separate always-on service.

Older clients that still open with initialize are handled too. Which era is in play is decided by the MCP-Protocol-Version header. See errors and limits for the supported list.

Two consequences worth knowing:

  • GET returns 405. There is no event stream to connect to.
  • JSON-RPC batching is rejected. Send one message per request.

Supported methods

Method Purpose
server/discover Stateless capability discovery. Returns protocol version, capabilities and server info.
initialize The legacy handshake. Still answered for older clients; negotiates the highest revision you both speak.
tools/list The tool catalog. Carries a one-hour cache hint scoped private.
tools/call Invoke a tool.
ping Health check. Returns an empty object.

tools/list is marked cacheScope: private deliberately. The catalog is currently identical for every user, but tool descriptions cite your custom columns by name, so a shared cache must never serve one account's vocabulary to another.

There are no MCP resources or prompts today — only tools.

A minimal call

curl -sX POST https://nlight.fit/api/mcp \
  -H "Authorization: Bearer $NLIGHT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

From revision 2026-07-28 onward the Mcp-Method header is required, and Mcp-Name is required for messages that address something. The server checks both against the request body and rejects disagreement, so an intermediary cannot route on one operation while the server performs another.

Browser requests are refused

Any request carrying an Origin header is rejected with 403 unless that origin is explicitly allowlisted by the server operator.

This is real access control rather than defensive tidying. The site applies a permissive Access-Control-Allow-Origin: * across /api/*, which is fine for endpoints that need a browser but not for one that returns a complete medical record. Genuine MCP clients are servers and send no Origin at all, so refusing every request that carries one costs nothing and closes both the CORS gap and the DNS-rebinding case the transport specification warns about.

Getting connected

  1. Mint an API token — see token management.
  2. Add the server to your client — see client setup.
  3. Ask your client to list tools, and confirm you get sixteen back.