Adaptyv Foundry MCP

A Model Context Protocol server that exposes the Adaptyv Foundry protein characterization API as MCP tools — so AI assistants like Claude and Cursor can interact with experiments, targets, sequences, results, and more in natural language.

The server speaks both stdio (local process) and Streamable HTTP (/mcp) for remote deployments.

Not affiliated with or endorsed by Adaptyv Bio. This is an independent project built to make programmatic access to Foundry-style workflows easier for builders and researchers.

Disclaimer — mock-only validation: The TypeScript SDK and MCP server were developed and tested only against a mock implementation of the Foundry API, generated from the public OpenAPI specification. The maintainer does not have access to the official Foundry API for end-to-end verification. When you point the server at a live Foundry account, request shapes, filters, error handling, or edge cases might not match production exactly, so you may encounter minor bugs or surprises. Issues and pull requests that align behavior with the real API are welcome.

---

Motivation

Adaptyv Foundry offers a powerful API for running protein characterization experiments. There's no official MCP server, which means AI assistants can't query or manage experiments without custom glue code.

This project bridges that gap. Drop the MCP server into Cursor (or any MCP-compatible client), point it at your Foundry token, and start asking questions like "what's the status of my latest experiment?" or "show me the results for experiment X" — no context switching, no custom scripts.

The server ships with a full mock mode backed by the official OpenAPI spec, so you can develop and test without a live Foundry account.

---

Deploy your own instance

The recommended path is a one-click Render deployment using the included Blueprint.

During one-click deploy, Render asks for FOUNDRY_API_TOKEN and MCP_HTTP_API_KEY: your Adaptyv Foundry API token and the secret clients send as Authorization: Bearer … on /mcp. You can change either later under Environment. Then install the server in your MCP client:

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "adaptyv-foundry": {
      "url": "https://<your-service>.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-MCP_HTTP_API_KEY>"
      }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "adaptyv-foundry": {
      "url": "https://<your-service>.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-MCP_HTTP_API_KEY>"
      }
    }
  }
}

GET /health is always open and unauthenticated — use it to verify the deployment is live.

Environment variables

Variable	Required	Description
FOUNDRY_API_TOKEN	Always	Your Adaptyv Foundry API token. Required even in mock mode.
MCP_HTTP_API_KEY	When MODE=http	Clients must send Authorization: Bearer <value> to /mcp.
FOUNDRY_USE_MOCK	No	Set to 1 to use in-memory mock data instead of live Foundry.
ALLOWED_ORIGINS	No	Comma-separated Origin allowlist for browser clients.

---

Demo deployment (mock)

A public demo instance runs with mock data — no real Foundry account needed. It's a great way to explore the available tools before deploying your own.

Cursor:

{
  "mcpServers": {
    "adaptyv-foundry-demo": {
      "url": "https://adaptyv-foundry-mcp.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer adaptyv-foundry-demo"
      }
    }
  }
}

Claude Desktop:

{
  "mcpServers": {
    "adaptyv-foundry-demo": {
      "url": "https://adaptyv-foundry-mcp.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer adaptyv-foundry-demo"
      }
    }
  }
}

Health check: https://adaptyv-foundry-mcp.onrender.com/health

The demo runs on Render's free tier and may spin down after inactivity — the first request after a cold start can take ~30 seconds.

---

Roadmap

• [ ] Fly.io one-click deployment — fly.toml is already in the repo; the goal is a proper deploy button and documented secrets workflow matching the Render experience.
• [ ] End-to-end tests against the live Foundry API — current tests run fully against mock data derived from the OpenAPI spec. The next step is an opt-in E2E suite that fires against a real FOUNDRY_API_TOKEN to validate the full request/response cycle.
• [ ] Leaner tool surface — revisit how many MCP tools we expose versus how Adaptyv API endpoints are grouped, so the tool list and descriptions don’t dominate the model’s context window or overwhelm typical chat sessions.

---

Also built: Adaptyv Notifications

If you want email alerts when your Foundry experiments change status, check out the companion project:

joostwmd/adaptyv-notifications — receives Foundry experiment webhooks and fans out configurable email notifications, with a small dashboard for managing destinations and delivery history.

---

Repository structure

Package	Description
packages/shared	Zod schemas and mock fixtures aligned with the Foundry OpenAPI spec.
packages/sdk	FoundryClient TypeScript SDK with optional mock client.
packages/mcp	MCP server (stdio + Streamable HTTP).

Local development

pnpm install
pnpm build

# Run MCP server locally with mock data (stdio)
pnpm mcp:mock

# Run with HTTP transport + MCP Inspector
cd packages/mcp && pnpm run inspector:http

# Tests
pnpm test        # SDK
pnpm test:mcp    # MCP server