Skip to main content

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.
The Foundry MCP is a hosted Model Context Protocol server that gives your agent access to the power of the Foundry API. 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.
A simulated MCP-aware client: the user asks the Foundry MCP to list experiments. The agent calls list_experiments, then summarises two active competitions in 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 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.
Foundry MCP request flow: an MCP-aware client calls the hosted MCP, which forwards to the Foundry public API; the API decides what to do and may schedule work in the Adaptyv lab.
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 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: 
export FOUNDRY_API_URL="https://foundry-api-public.adaptyvbio.com/api/v1"
export FOUNDRY_API_TOKEN="<your-foundry-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. 
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. 
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. 
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. 
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,"<YYYY-MM-DD>"))' \
    --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: 
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, then register the server with the token in an Authorization header: 
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). 
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:
{
  "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.

​
Where to next

API Reference

The full REST API the MCP wraps — resource groups, status values, filter syntax, webhook payloads.

Getting Started

First-time orientation to Adaptyv Foundry: experiment types, the project workflow, and how to set up your organization.