> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adaptyvbio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Drive Adaptyv experiments through Claude Code, Claude Desktop, or any MCP-aware client using natural language.
The Cloud Lab MCP is a hosted Model Context Protocol server that gives your agent access to the power of the [Adaptyv API](/api-reference/api-introduction).
Point an MCP-aware client at it - Claude Code, Claude Desktop, Cursor, your own agent - and the same things you would do with `curl` against `devs.adaptyvbio.com` become things you can ask for in plain English: list experiments, fetch results, quote a screen, confirm a quote.
The agent picks the right tool, fills in the parameters, and shows you the response.
## Why use it
You already have the REST API, which is great for fully automated pipelines. But you probably also have interactive workflows or ad-hoc questions.
The MCP is perfect for these, when you do not want to compose API queries for a one-off question.
Listing the five most recent experiments, pulling the kinetics for a specific run, comparing two cost estimates - these are short, exploratory tasks that benefit from an agent doing the wiring.
You stay in your editor or chat client; the agent handles the HTTP plumbing.
Pairing the API with reasoning is the other concrete win. Agents are great at using `curl`, but not every agentic environment will give you access to the CLI and the ability to pass the auth token.
With the hosted MCP, every MCP-enabled agent can fetch results and then explain whether a `KD` looks tight for your target class, compare a new screen against historical baselines, or sanity-check a quote before you confirm it.
You get retrieval and analysis in the same turn, against the same data.
We also have plans to enrich the MCP with [interactive MCP apps](https://modelcontextprotocol.io/extensions/apps/overview) and other MCP-specific features, so monitor this page for updates.
## How it fits together
The hosted endpoint is `https://mcp.adaptyvbio.com/mcp/`. Every Adaptyv REST endpoint shows up as an MCP tool with the same parameters and the same authorization scopes.
| Environment | MCP endpoint | Adaptyv API it fronts |
| ----------------- | ----------------------------------------- | -------------------------------------------- |
| Production | `https://mcp.adaptyvbio.com/mcp/` | `https://devs.adaptyvbio.com/api/v1` |
| Testing (sandbox) | `https://mcp.testing.adaptyvbio.com/mcp/` | `https://devs.testing.adaptyvbio.com/api/v1` |
Most users only need production. The testing sandbox is a separate environment with its own accounts and tokens from the [testing portal](https://foundry.testing.adaptyvbio.com) — handy for trying calls that create or change data without touching real experiments.
Keep the trailing slash on the endpoint URL (`/mcp/`). It is the server's canonical OAuth resource identifier: a client that registers the URL without it can fail OAuth discovery with a "protected resource does not match" error, even though plain (token-header) tool calls would still work.
This means that (for now) whatever you can do with the API, you can do with the MCP, and vice versa. Check out the [API reference](/api-reference/api-introduction) to see a list of endpoints (or ask your agent to figure it out for you).
## Sample queries
The examples below show the questions asked to an agent and the equivalent `curl` query an MCP call maps to. All queries presume the following environment variables to be set:
```sh theme={null}
export FOUNDRY_API_URL="https://devs.adaptyvbio.com/api/v1"
export FOUNDRY_API_TOKEN=""
```
***
**"List the latest five experiments and tell me which ones are awaiting my action."**
The agent calls `list_experiments`, reads each entry's `status`, and flags the ones at `Draft` or `QuoteSent`.
```sh theme={null}
curl -G "$FOUNDRY_API_URL/experiments" \
-H "Authorization: Bearer $FOUNDRY_API_TOKEN" \
--data-urlencode "sort=desc(created_at)" \
--data-urlencode "limit=5" \
| jq '.items[] | select(.status | IN("Draft", "QuoteSent"))
| {code, name, status}'
```
***
**"Show me the binding kinetics for experiment ABC-001-042 and tell me whether the K\_D looks tight enough for a follow-up screen."**
`get_experiment` resolves the code, `get_results` pulls the kinetic constants, and the agent compares K\_D against typical cutoffs for that target class.
```sh theme={null}
curl "$FOUNDRY_API_URL/experiments/ABC-001-042/results" \
-H "Authorization: Bearer $FOUNDRY_API_TOKEN"
# Then read kinetic constants out of the response yourself
# and look up typical K_D cutoffs for the target.
```
***
**"Quote a screening assay against the EGFR target from the catalog, for these three sequences."**
The agent searches the catalog, picks a self-service target, then runs `cost_estimate` and returns a USD-cents breakdown.
```sh theme={null}
TARGET_ID=$(curl -sG "$FOUNDRY_API_URL/targets" \
-H "Authorization: Bearer $FOUNDRY_API_TOKEN" \
--data-urlencode "search=EGFR" \
--data-urlencode "selfservice_only=true" \
--data-urlencode "limit=1" \
| jq -r '.items[0].id')
curl -X POST "$FOUNDRY_API_URL/experiments/cost-estimate" \
-H "Authorization: Bearer $FOUNDRY_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"experiment_spec": {
"experiment_type": "screening",
"method": "bli",
"target_id": "'"$TARGET_ID"'",
"sequences": {
"s1": "EVQLVESGGGLVQPGG...",
"s2": "QVQLVQSGAEVKKPGA...",
"s3": "DIQMTQSPSSLSASVG..."
}
}
}'
```
***
**"Find any experiment from the last quarter where one of the candidates beat 50nM affinity, and group by target."**
The agent paginates `list_results` with a date filter, pulls the affinity values, and groups by `target_id` in one pass.
```sh theme={null}
OFFSET=0; ALL="[]"
while :; do
PAGE=$(curl -sG "$FOUNDRY_API_URL/results" \
-H "Authorization: Bearer $FOUNDRY_API_TOKEN" \
--data-urlencode 'filter=and(eq(experiment_type,"affinity"),gte(created_at,""))' \
--data-urlencode "limit=100" \
--data-urlencode "offset=$OFFSET")
COUNT=$(jq '.items | length' <<< "$PAGE")
ALL=$(jq -s '.[0] + .[1].items' <(echo "$ALL") <(echo "$PAGE"))
[ "$COUNT" -lt 100 ] && break
OFFSET=$((OFFSET + 100))
done
# Then filter ALL for affinity below 50 nM and group by target_id.
```
## Connect Claude Code
Two paths exist: an OAuth flow that uses your Adaptyv portal session, or a long-lived API token of the kind you'd use against the REST API. Both end up with the same downstream authorization; pick whichever fits your context.
### Authentication via OAuth
OAuth is the easiest path for interactive use on your own machine. Register the server without an `Authorization` header:
```sh theme={null}
claude mcp add \
--scope user \
--transport http \
adaptyv-cloud-lab-mcp \
https://mcp.adaptyvbio.com/mcp/
```
The first time Claude Code reaches the server, your browser opens and asks you to sign in via the [Adaptyv portal](https://foundry.adaptyvbio.com). Confirm consent on the dialog and Claude Code stores the credential locally for future tool calls. The credential expires with your portal session; you can also revoke it from the portal under Organization → Settings → Tokens.
### Authentication via API tokens
For automation, CI, or shared machines, use a long-lived API token instead. Obtain one from the Adaptyv portal as described in [Getting an API token](/api-reference/api-introduction#getting-an-api-token), then register the server with the token in an `Authorization` header:
```sh theme={null}
claude mcp add \
--scope user \
--transport http \
adaptyv-cloud-lab-mcp \
https://mcp.adaptyvbio.com/mcp/ \
--header "Authorization: Bearer $FOUNDRY_API_TOKEN"
```
Never paste a Adaptyv token into an LLM chat. Configure it once in your MCP client config — the client forwards the header on every tool call, so the model never sees the token in its context.
The sandbox is a separate environment. Sign in at the [testing portal](https://foundry.testing.adaptyvbio.com) for an account and token, then point your client at the testing endpoint with a testing token:
```sh theme={null}
claude mcp add \
--scope user \
--transport http \
adaptyv-cloud-lab-mcp-testing \
https://mcp.testing.adaptyvbio.com/mcp/ \
--header "Authorization: Bearer $FOUNDRY_TESTING_TOKEN"
```
For the `curl` examples on this page, set `FOUNDRY_API_URL="https://devs.testing.adaptyvbio.com/api/v1"`.
### Verify
`--scope user` writes the registration to `~/.claude.json` and follows you across projects. Use `--scope project` instead if you want the connection to live in the repo's `.mcp.json` and be shared with collaborators (without the token — Claude Code stores secrets per user).
```sh theme={null}
claude mcp list
```
Expected output includes the server name and `✓ Connected`, followed by the tool count. If you see `✗ Failed to connect`, the credential is the most likely cause — sign in again (for OAuth) or re-issue your token from the portal and re-register.
## Other MCP clients
Any MCP client that speaks streamable HTTP works. The configuration is always two pieces: a URL and either an OAuth flow or a bearer header.
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:
```json theme={null}
{
"mcpServers": {
"adaptyv-cloud-lab-mcp": {
"type": "http",
"url": "https://mcp.adaptyvbio.com/mcp/",
"headers": {
"Authorization": "Bearer YOUR_FOUNDRY_TOKEN_HERE"
}
}
}
}
```
Restart Claude Desktop. The Adaptyv tools appear in the tool picker.
Any client that supports MCP over streamable HTTP accepts the same three values:
```
Transport: http (streamable)
URL: https://mcp.adaptyvbio.com/mcp/
Headers: Authorization: Bearer
```
Consult your client's documentation for where to paste them.
## Where to next
The full REST API the MCP wraps — resource groups, status values, filter syntax, webhook payloads.
First-time orientation to Adaptyv Foundry: experiment types, the project workflow, and how to set up your organization.