> ## 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 Foundry experiments through Claude Code, Claude Desktop, or any MCP-aware client using natural language.
# MCP Server
> Drive Foundry experiments through Claude Code, Claude Desktop, or any MCP-aware client using natural language.
The Foundry MCP is a hosted Model Context Protocol server that gives your agent access to the power of the [Foundry 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 `foundry-api-public.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://foundry-mcp.adaptyv.bio/mcp/`. Every Foundry REST endpoint shows up as an MCP tool with the same parameters and the same authorization scopes.
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://foundry-api-public.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 Foundry 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 \
foundry-api \
https://foundry-mcp.adaptyv.bio/mcp/
```
The first time Claude Code reaches the server, your browser opens and asks you to sign in via the Foundry portal. 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 Foundry 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 \
foundry-api \
https://foundry-mcp.adaptyv.bio/mcp/ \
--header "Authorization: Bearer $FOUNDRY_API_TOKEN"
```
Never paste a Foundry 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.
### 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": {
"foundry-api": {
"type": "http",
"url": "https://foundry-mcp.adaptyv.bio/mcp/",
"headers": {
"Authorization": "Bearer YOUR_FOUNDRY_TOKEN_HERE"
}
}
}
}
```
Restart Claude Desktop. The Foundry tools appear in the tool picker.
Any client that supports MCP over streamable HTTP accepts the same three values:
```
Transport: http (streamable)
URL: https://foundry-mcp.adaptyv.bio/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.