# Connect an agent in **three steps**.

The Uphealth MCP server wraps the Signal cued-message API as agent-callable tools, so an AI agent — Claude Desktop, Cursor, or any MCP client — can open a patient stream and run the cue loop with no glue code. It speaks Streamable HTTP at one endpoint and authenticates with the same sandbox key. One tool — the keyless lookup_health_fact — needs no key at all, so an agent can call Uphealth before it has one.

> **Before you begin**
>
> You need a Discovery sandbox key `up_sandbox_…` — free, self-serve, and shown once on your dashboard at signup. The MCP server is the Discovery sandbox: a curated five-topic federal subset, Display-only, no PHI.
>
> One tool needs no key at all: `lookup_health_fact` returns one already-public federal fact for any question — the true zero-setup first call. Every other tool authenticates with the sandbox key.
>
> [Get a sandbox key →](https://uphealth.us/signup)

### Get your key

Copy a sandbox key from your dashboard. The agent sends it as a Bearer token on every call; the MCP server passes it through to the API unchanged, and the API enforces auth, scopes, and tenancy. Never hard-code a key in config you commit.

### Configure your client

Point your MCP client at the endpoint and add the Authorization header. Two common clients:

**Claude Desktop** — open Settings, then Connectors, then Add custom connector, paste `https://mcp.uphealth.us/mcp` and set the Authorization header. Or edit the config file directly:

**claude_desktop_config.json**

```json
{
  "mcpServers": {
    "uphealth": {
      "type": "http",
      "url": "https://mcp.uphealth.us/mcp",
      "headers": {
        "Authorization": "Bearer up_sandbox_…"
      }
    }
  }
}
```

**Cursor** — add an entry to `.cursor/mcp.json`:

**.cursor/mcp.json**

```json
{
  "mcpServers": {
    "uphealth": {
      "url": "https://mcp.uphealth.us/mcp",
      "headers": { "Authorization": "Bearer up_sandbox_…" }
    }
  }
}
```

### Verify the connection

Before wiring an agent, confirm the server answers with the official MCP Inspector. It lists the five tools and lets you call each one by hand.

**Terminal**

```
$ npx @modelcontextprotocol/inspector \
  --transport streamable-http \
  --url https://mcp.uphealth.us/mcp \
  --header "Authorization: Bearer up_sandbox_…"
```

### Make the first tool call

`list_sandbox_topics` has no side effects and needs only the metadata scope — the safest first call. It returns the five sandbox topic labels and the sandbox template id, never the messages themselves.

**result**

```
// list_sandbox_topics → result
{
  "topic_labels": [
    "heart-health-basics",
    "diabetes-basics",
    "diet-eat-better",
    "exercise-move-more",
    "screenings-recommended"
  ],
  "template_id_for_sandbox": "general_wellness_daily",
  "_meta": { "api_version": "1.0", "no_medical_advice": true, "delivery_mode": "display", … }
}
```

From there, `create_patient_stream` opens a stream and returns the first cue, and `get_next_cued_message` submits the patient's response and returns the next one. The full loop is on the [MCP tools reference](https://uphealth.us/docs/mcp-tools).

The server also exposes a `signal://catalog` resource — read it first to pick a template and pre-satisfy its gating — plus `pick_template` and `evaluate_signal` prompts. Both are covered in the [MCP tools reference](https://uphealth.us/docs/mcp-tools).

> **The one rule**
>
> `get_next_cued_message` refuses to advance without the prior message's feedback — it returns an error, not the next cue. This is structural, not a policy: the engine cannot pick the next-right message without the patient's signal on the last one. Send a `feedback` block on every call after the first.

> **Sandbox, quota, and upgrade**
>
> The MCP server is Display-only and free — no PHI, no BAA, capped at 50 cues per calendar month (UTC). Exceed the cap and `get_next_cued_message` returns an upgrade signal: the message names your usage and the upgrade URL, so the agent can route to a paid tier inline. Production Deliver mode — Uphealth sends, BAA-gated — runs through the REST API after upgrade; the MCP surface is sandbox evaluation and agent integration at v1.

## What is next

- [MCP tools](https://uphealth.us/docs/mcp-tools) — The five tools — inputs, outputs, the feedback rule, and the error model.
- [Cues & feedback](https://uphealth.us/docs/concepts-cues) — The response_action archetypes and the idempotency key the cue tool uses.
- [Sample data](https://uphealth.us/docs/sandbox) — The five sandbox topics and the federal content behind them.
- [Sandbox → production](https://uphealth.us/docs/live-promote) — Promote to a paid tier for production volume and Deliver mode.

---

_Uphealth Signal developer docs · [View on uphealth.us](https://uphealth.us/docs/mcp-quickstart) · OpenAPI spec: https://uphealth.us/openapi/signal-v1.yaml · Verified against API v1 on 2026-07-22._