Use the Sahha MCP Server in Claude Code

Connect your Sahha MCP server to Claude Code to query live health data while you build — explore data shapes, debug integrations, and scaffold code faster.

What you are building

Most developers building on Sahha spend time in two modes: exploring the API to understand what data looks like, and writing code to consume that data in their app. Normally these are separate — you’re jumping between docs, the Query Builder, and your editor.

With your Sahha MCP server connected to Claude Code, both happen in the same place. You can ask Claude Code “what does a readiness score response look like for this profile?” and get a real answer from your actual Sahha account — then immediately ask it to write the code that handles that shape.

By the end of this tutorial you will be able to:

• Connect your Sahha MCP server to Claude Code
• Query live Sahha data from inside your development workflow
• Use real data shapes to scaffold integration code accurately
• Debug Sahha responses without leaving your editor

Prerequisites

This tutorial assumes you have already completed Build a Sahha MCP Server. You will need:

• The compiled Sahha MCP server from that tutorial (dist/index.js)
• A Sahha account with at least one profile that has data (create a sample profile)
• Claude Code installed (npm install -g @anthropic-ai/claude-code)

How Claude Code uses MCP servers

Claude Code supports MCP servers as a source of tools it can call during agentic tasks. When your Sahha MCP server is connected, Claude Code gains four new tools — get_scores, get_biomarkers, get_archetypes, and get_profile — and can call them automatically when your request requires live data.

This is different from Claude Desktop, where you chat with Claude in a UI. Claude Code is a terminal-based coding agent, so the MCP tools are most useful when combined with file reading, code generation, and shell execution — the things Claude Code does natively.

1. Add the Sahha MCP server to Claude Code

Run this command from the root of the project you are building with Sahha:

claude mcp add --scope project --transport stdio \
  --env SAHHA_CLIENT_ID=your-client-id \
  --env SAHHA_CLIENT_SECRET=your-client-secret \
  --env SAHHA_BASE_URL=https://sandbox-api.sahha.ai \
  sahha -- node /absolute/path/to/sahha-mcp-server/dist/index.js

Replace /absolute/path/to/sahha-mcp-server with the actual path to your compiled server.

This creates or updates .mcp.json in your project root with the following structure:

{
  "mcpServers": {
    "sahha": {
      "command": "node",
      "args": ["/absolute/path/to/sahha-mcp-server/dist/index.js"],
      "env": {
        "SAHHA_CLIENT_ID": "your-client-id",
        "SAHHA_CLIENT_SECRET": "your-client-secret",
        "SAHHA_BASE_URL": "https://sandbox-api.sahha.ai"
      }
    }
  }
}

You can also create or edit .mcp.json directly if you prefer.

2. Start Claude Code with MCP enabled

In your project directory, start Claude Code:

claude

On startup, Claude Code connects to the configured MCP servers. To verify the Sahha server is connected, run:

claude mcp list

You should see sahha listed with its four tools. If you see a connection error, double-check the absolute path to dist/index.js in your config.

3. Explore live data shapes

The most immediate use of the MCP connection is understanding what Sahha data actually looks like for your profiles — before you write any code.

Try these prompts in Claude Code — replace your-external-id with a real externalId from your Sahha account:

Explore scores:

Fetch the scores for profile "your-external-id" and show me the full response shape.

Understand a specific score type:

Get the sleep score for "your-external-id" for the past 7 days and explain what each field means.

Explore biomarkers:

What biomarkers are available for "your-external-id" in the sleep category? Show me the raw response.

Check archetypes:

What archetypes is "your-external-id" assigned to, and what do they indicate?

Claude Code will call your MCP server, get real data from Sahha, and return it with context. This is significantly faster than switching to the Query Builder, copying a response, and pasting it into a doc.

4. Scaffold integration code from real data

Once you have seen real response shapes, you can use them to generate accurate integration code immediately.

Generate a TypeScript type from a live response:

Fetch the scores response for "your-external-id" and generate a TypeScript interface
that matches the shape exactly.

Build a webhook handler using real data:

Get a scores response for "your-external-id" and write a Node.js function that
processes a Sahha webhook payload in the same shape and stores it in Supabase.

Generate a UI component from real data:

Fetch the scores for "your-external-id" and build a React component that renders
each score as a card with the score value, state, and created date.

Because Claude Code has access to both the live data and your codebase, it can generate code that matches your actual response shape — not a generic example that may not match what Sahha returns for your account and data.

5. Debug Sahha responses during development

When you are integrating Sahha into an app and something is not behaving as expected, the MCP server makes it easy to isolate whether the issue is in the API response or in your code.

Check what a fresh response looks like:

Fetch the readiness scores for "your-external-id" for today and compare the shape
to the type definition in src/types/sahha.ts. Are there any mismatches?

Investigate missing data:

Fetch all score types for "your-external-id" for the past 30 days. Are there any
days with no data? What could explain the gaps?

Validate your parsing logic:

Get the biomarkers for "your-external-id" in the activity category. Then look at
how src/utils/parseBiomarkers.ts processes this data and tell me if
the parsing logic handles every field correctly.

This workflow — fetch live data, compare it to your code, identify the mismatch — is much faster than adding console logs, triggering a webhook, and reading logs.

Example workflow: building a scores display feature

Here is a complete example of how this looks in practice.

You are adding a health scores screen to your app. Instead of starting from docs and example payloads, you start from real data:

Step 1 — understand the data:

Fetch all score types for "your-external-id" for the past week. What types are
available, what are their value ranges, and what states are possible?

Step 2 — generate the type:

Based on the scores response you just fetched, generate a TypeScript
interface called SahhaScore.

Step 3 — scaffold the component:

Using the SahhaScore interface, build a React Native component called
ScoreCard that displays the score type, value as a percentage, state
as a colour-coded badge, and the date.

Step 4 — write the fetch logic:

Write a custom hook called useScores that fetches scores from our
backend endpoint /api/scores/:externalId and returns them typed
as SahhaScore[].

Each step builds directly on the real data shape from your Sahha account, so the generated code reflects what your integration will actually receive.

Tips for working with Sahha data in Claude Code

Be specific about the profile ID. Claude Code needs a real externalId to fetch data. Use a sample profile or your own test profile consistently.

Use date ranges. Sahha data is time-series. Specifying startDateTime and endDateTime in your prompts gets you more focused responses, especially for biomarkers which can return large payloads.

Fetch before generating. Get the live data first in one prompt, then ask for code generation in the next. This gives Claude Code the actual shape in its context before it writes any types or handlers.

Combine with your codebase. The real power of this workflow is that Claude Code can see both the live Sahha data and your existing files at the same time. Prompts like “fetch this data and compare it to my existing type definition” or “get this response and update my parser to handle it correctly” are uniquely possible here.

What to build next

Now that you can query live Sahha data inside your development workflow, the next step in the series is making the MCP server available beyond your local machine:

• Deploy the Sahha MCP Server remotely — switch from stdio to Streamable HTTP so any MCP client, on any machine, can connect to a single hosted endpoint