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

Client setup

Every client needs the same three things: the endpoint https://nlight.fit/api/mcp, the HTTP transport, and an Authorization: Bearer header carrying your token.

Mint a token first — see token management.

Claude Code

claude mcp add --transport http nlight https://nlight.fit/api/mcp \
  --header "Authorization: Bearer rt_ro_your_token_here"

Confirm it connected:

claude mcp list

Claude Desktop

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "nlight": {
      "type": "http",
      "url": "https://nlight.fit/api/mcp",
      "headers": {
        "Authorization": "Bearer rt_ro_your_token_here"
      }
    }
  }
}

Restart Claude Desktop. The tools appear under the server name nlight.

Cursor

Add the server to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "nlight": {
      "url": "https://nlight.fit/api/mcp",
      "headers": {
        "Authorization": "Bearer rt_ro_your_token_here"
      }
    }
  }
}

A custom client

The endpoint is ordinary HTTP, so any language works. Nothing MCP-specific is required beyond setting the headers correctly.

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/call" \
  -H "Mcp-Name: get_streak" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_streak", "arguments": { "metric": "vitamins" } }
  }'

Three rules to build against:

  • Send one JSON-RPC message per request. Arrays are rejected.
  • From protocol revision 2026-07-28, Mcp-Method is required and must match the body. Mcp-Name is required for tools/call and must match params.name.
  • Do not send an Origin header. Requests carrying one are refused as browser traffic.

Verifying the connection

Ask your client to list the available tools. You should get sixteen. If you would rather check directly:

curl -sX POST https://nlight.fit/api/mcp \
  -H "Authorization: Bearer $NLIGHT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'

Troubleshooting

Symptom Cause
401 with WWW-Authenticate: Bearer No token, or one that is unknown, revoked or expired. Mint a new one.
403 Insufficient scope The token lacks read. Mint one with --scopes read.
403 Requests from browser origins are not accepted Your client is sending an Origin header. Remove it.
405 Method not allowed Something issued a GET. The endpoint is POST-only; there is no event stream.
-32020 Header mismatch Mcp-Method or Mcp-Name disagrees with the body, or is missing on protocol 2026-07-28.
400 Unsupported protocol version Pick one from error.data.supported in the response.
429 Rate limited at 120 requests per minute. Honour Retry-After.

Good first questions

Once connected, these exercise different parts of the tool surface:

  • "What's my current vitamins streak?"
  • "Pull my recovery context for the last two weeks and tell me if I'm overreaching."
  • "What correlates with my HRV? Use the correlation edges, not the narrative."
  • "Get my daily features for the last 90 days for sleep hours and recovery, and check whether the relationship holds at a one-day lag."

The last one is what the warehouse tools exist for: the client does the analysis itself rather than reading a conclusion.