API Documentation
Overview
Python SDK Reference
End to End example
List custom tools
Get a custom tool
Create a custom tool
Update a custom tool
Delete a custom tool
Create a source upload
Build a custom tool
List build logs
Cancel a custom tool build
Run a custom tool
Publish a custom tool version
List custom tool versions
MCP Server
Tamarind offers a Model Context Protocol (MCP) server that allows AI assistants and other applications to access Tamarind's computational biology tools. With the MCP server, you can:
- Submit jobs for any tool on Tamarind, including structure prediction, protein design, docking, and more
- Query job status and retrieve results
- Upload and manage input files
- Access all Tamarind tools through natural language
Example prompts you can use with your AI assistant:
- "Submit an RFDiffusion job to design a binder for this target protein"
- "Check the status of my recent structure prediction jobs"
- "Get the results from my batch antibody design job"
Requirements
To use Tamarind's MCP server, you need:
- A Tamarind account - Sign up here
- OAuth credentials (see OAuth 2.1 below) or an API key - Get yours at API Key or email info@tamarind.bio
- A compatible MCP client - Such as Claude.ai, Claude Code, VS Code, Codex, or other MCP-compatible tools
Authentication
Tamarind MCP server supports two authentication methods:
OAuth 2.1
OAuth authentication provides user-specific access control and is the recommended method for most users.
Client ID: V8apuKVjc88f0FNP
Authorization URL: https://clerk.tamarind.bio/oauth/authorize
Token URL: https://clerk.tamarind.bio/oauth/token
Request a redirect URI
For enterprise gateways / custom MCP clients that hit a redirect_uri mismatch
Enterprise gateways and custom MCP clients often use their own OAuth callback URL. If you see a redirect_uri mismatch error, submit the exact URI your client sends and we will add it to our OAuth allowlist.
Sign in to request a redirect URI registration.
API Key
API key authentication is a simpler alternative suitable for personal use or automation. Pass your API key via the x-api-key header. View your API key at API Key or email info@tamarind.bio to request access.
Server URL: https://mcp.tamarind.bio/mcp
Client Setup Instructions
Claude.ai (Web)
Claude.ai provides the simplest way to connect to Tamarind's MCP server with no installation required.
Prerequisites
- Claude.ai account (free or paid)
Setup Steps
- Go to claude.ai
- Click on your profile icon → Settings
- Navigate to Connectors
- Click Add custom connector
- Fill in the connector details:
- Name: Tamarind
- Remote MCP server URL: https://mcp.tamarind.bio/mcp
- Expand Advanced settings and enter your Tamarind OAuth credentials (both required):
- OAuth Client ID: V8apuKVjc88f0FNP
- OAuth Client Secret: See the Client Secret in the Authentication section above
- Click Add
- You'll be redirected to sign in with your Tamarind account and authorize the connection
Once connected, you can use Tamarind tools directly in your Claude.ai conversations!
Uploading files? Large files are streamed to mcp.tamarind.bio with a curl command. This client's sandbox blocks outbound network by default, so the upload fails with "network unreachable" until you allow the domain: open Settings → Capabilities, enable Allow network egress, and add mcp.tamarind.bio under Additional allowed domains. Connecting the MCP server itself does not need this - only the upload curl does. (Files ≤ 4 MB can be uploaded inline without it.)
Claude Code (CLI)
Add the Tamarind MCP server directly from the command line:
1claude mcp add --transport http tamarind https://mcp.tamarind.bio/mcp \
2 --header "x-api-key:YOUR_API_KEY_HERE"Replace YOUR_API_KEY_HERE with your API key, then restart Claude Code.
Claude Desktop
Add Tamarind from the Connectors UI, or edit the configuration file directly.
Connectors UI (recommended)
The same four values used on Claude.ai:
- Open Settings → Connectors
- Click Add → Add custom connector
- Fill in the connector details:
- Name: Tamarind
- Remote MCP server URL: https://mcp.tamarind.bio/mcp
- Expand Advanced settings and enter your Tamarind OAuth credentials (both required):
- OAuth Client ID: V8apuKVjc88f0FNP
- OAuth Client Secret: See the Client Secret in the Authentication section above
- Click Add
- Sign in with your Tamarind account to authorize the connection
Tamarind then appears in your connectors list, and its tools are available in new conversations.
API Key Authentication (config file)
- Get your API key from API Key
- Open your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Add the Tamarind MCP server configuration:
1{
2 "mcpServers": {
3 "tamarind": {
4 "command": "npx",
5 "args": [
6 "mcp-remote",
7 "https://mcp.tamarind.bio/mcp",
8 "--header",
9 "x-api-key:YOUR_API_KEY_HERE"
10 ]
11 }
12 }
13}Replace YOUR_API_KEY_HERE with your API key, then restart Claude Desktop.
OAuth Authentication (config file)
- Get your OAuth credentials from the Authentication section above
- Open your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Add the Tamarind MCP server configuration (see below)
- Restart Claude Desktop
- The first time you use Tamarind tools, you'll be prompted to authenticate in your browser
- Log in with your Tamarind account
1{
2 "mcpServers": {
3 "tamarind": {
4 "command": "npx",
5 "args": [
6 "mcp-remote",
7 "https://mcp.tamarind.bio/mcp",
8 "3334",
9 "--static-oauth-client-info",
10 "{\"client_id\":\"V8apuKVjc88f0FNP\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}"
11 ]
12 }
13 }
14}Replace YOUR_CLIENT_SECRET with your client secret (revealed in the Authentication section above), then restart Claude Desktop. Once connected, you'll see Tamarind appear in your connectors list.
Uploading files? Large files are streamed to mcp.tamarind.bio with a curl command. This client's sandbox blocks outbound network by default, so the upload fails with "network unreachable" until you allow the domain: open Settings → Capabilities, enable Allow network egress, and add mcp.tamarind.bio under Additional allowed domains. Connecting the MCP server itself does not need this - only the upload curl does. (Files ≤ 4 MB can be uploaded inline without it.)
Claude Science
Claude Science registers its own OAuth client, so there are no credentials to paste - leave Advanced settings empty.
Setup Steps
- Open Settings → Connectors
- Click Add connector → Remote URL
- Fill in the connector details:
- Name: Tamarind
- Remote MCP server URL: https://mcp.tamarind.bio/mcp
- Click Add
- Click Connect, then sign in with your Tamarind account to authorize the connection
Tamarind then appears under Custom in your connectors list, and its tools are available in new conversations.
Connect using API
To set it up, add your API key:
- Open Settings → Credentials → Add
- Set Name to
TAMARIND_API_KEY - Set Value to your API key, copied from API Key
VS Code
VS Code supports MCP servers through GitHub Copilot Chat. Add the following to .vscode/mcp.json in your workspace (or use Cmd+Shift+P → "MCP: Add Server"):
1{
2 "servers": {
3 "tamarind": {
4 "type": "http",
5 "url": "https://mcp.tamarind.bio/mcp",
6 "headers": {
7 "x-api-key": "${input:tamarind-api-key}"
8 }
9 }
10 },
11 "inputs": [
12 {
13 "type": "promptString",
14 "id": "tamarind-api-key",
15 "description": "Tamarind API Key",
16 "password": true
17 }
18 ]
19}VS Code will prompt you for the API key on first use. You can then use @tamarind in Copilot Chat to access Tamarind tools.
Refer to the VS Code MCP documentation for more details.
ChatGPT (Web)
Tamarind Bio is published in the ChatGPT plugin directory. No configuration, API key, or installation is required.
- Go to chatgpt.com
- Open Plugins
- Search for Tamarind Bio
- Click Install
- Sign in with your Tamarind account when prompted to authorize the connection
Once connected, Tamarind tools are available directly in your ChatGPT conversations.
Codex (OpenAI)
Install the published Tamarind Bio plugin in the Codex desktop app. Adding the server by hand is only needed if you installed our plugin repository as a marketplace instead.
Install the plugin (recommended)
- Open Plugins in the Codex sidebar
- Search for Tamarind Bio
- Click Install and complete the authorization prompt
The plugin brings the MCP server and all Tamarind skills with it. Nothing else to configure.
Add the server manually
Use this if you added Tamarind-Bio/tamarind-agent-plugin as a plugin marketplace. That install registers the server, so tamarind appears under MCPs → From plugins, but the entry carries no credentials and its Authenticate button will not connect it. Connect it with an API key instead:
- Get your API key from API Key
- Open Settings → Plugins → MCPs → Add server
- Set Name to
tamarind - Set Type to Streamable HTTP (the STDIO default is for local servers and will not connect)
- Set URL to
https://mcp.tamarind.bio/mcp - Under Headers, add
x-api-keywith your API key as the value - Save, then start a new task so Codex discovers the tools
Codex CLI
- Set your API key as an environment variable in your shell profile (
~/.zshrcor~/.bashrc):
1export TAMARIND_API_KEY="your-api-key-here"- Add the following to
~/.codex/config.toml:
1[mcp_servers.tamarind]
2url = "https://mcp.tamarind.bio/mcp"
3env_http_headers = { "x-api-key" = "TAMARIND_API_KEY" }- Launch Codex and use Tamarind tools directly
Antigravity (Google)
Antigravity connects with the OAuth credentials above. Add the server to its MCP config, then authorize in the browser - there is nothing to paste back into the editor.
- Open Settings → Installed MCP Servers and click Open MCP Config
- Add the Tamarind server:
1{
2 "mcpServers": {
3 "tamarind": {
4 "serverUrl": "https://mcp.tamarind.bio/mcp",
5 "oauth": {
6 "clientId": "V8apuKVjc88f0FNP",
7 "clientSecret": "YOUR_CLIENT_SECRET"
8 }
9 }
10 }
11}- Replace
YOUR_CLIENT_SECRETwith the Client Secret from the Authentication section above, then save the file - Back in Installed MCP Servers, click Authenticate next to
tamarind - Sign in with your Tamarind account to authorize the connection
Until you authorize, the server shows Error: calling "initialize": Unauthorized. That is expected - it means Antigravity has the server but no token yet, and it clears once Authenticate completes.
Other MCP Clients
Any MCP-compatible client (Cursor, Windsurf, or custom implementations) can connect to the Tamarind MCP server at https://mcp.tamarind.bio/mcp using API key authentication. Pass your key via the x-api-key header.
Refer to your specific client's documentation for configuration details. If you need help, email info@tamarind.bio.
Available Tools
The Tamarind MCP server exposes 30 tools. Expand any tool to see its parameters. Each tool declares whether it only reads data or may modify it, so your MCP client can flag writes before running them.
Read-only - Safe queries that never modify your data.
estimateTimeRead-onlyEstimate how LONG a job will run and how many WEIGHTED (compute) HOURS it will cost — BEFORE submitting anything. Use it to plan a run, compare tools, warn the user about a slow or expensive job, or budget a design loop.
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | |
| settings | object | Yes | |
| jobName | string | No | (default: "estimate") |
| atomCount | integer | No | (default: null) |
getAvailableToolsRead-onlyGet list of all available tools/job types in the Tamarind platform.
| Parameter | Type | Required | Description |
|---|---|---|---|
| modality | string | No | (default: null) |
| function | string | No | (default: null) |
| category | string | No | (default: null) |
| tag | string | No | (default: null) |
| search | string | No | (default: null) |
| custom | boolean | No | (default: null) |
getFileStatsRead-onlyGet summary statistics about available files (counts by type).
No parameters.
getFilesRead-onlyList files available in the Tamarind workspace with filtering.
| Parameter | Type | Required | Description |
|---|---|---|---|
| types | string | No | (default: null) |
| search | string | No | (default: null) |
| limit | integer | No | (default: 100) |
| offset | integer | No | (default: 0) |
| includeMetadata | boolean | No | (default: false) |
getFoldersRead-onlyRetrieve a list of folders in the user's storage
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Maximum number of folders to return (default: 20) |
| offset | integer | No | Number of folders to skip (default: 0) |
| loadAll | enum | No | Load all folders without pagination - one of: true |
getJobFileRead-onlyDownload a specific file from a job's S3 directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | Yes | |
| fileName | string | Yes | |
| maxSizeMB | integer | No | (default: 10) |
getJobLogsRead-onlyFetch the output logs for a specific job from S3.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | Yes | |
| maxLines | integer | No | (default: 500) |
getJobSchemaRead-onlyGet the detailed parameter schema for a specific job type.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobType | string | Yes |
getJobsRead-onlyList your jobs (status, timing, score), or fetch one job by name.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | No | (default: null) |
| batch | string | No | (default: null) |
| startKey | string | No | (default: null) |
| limit | integer | No | (default: 1000) |
| organization | boolean | No | (default: null) |
| includeSubjobs | boolean | No | (default: null) |
| jobEmail | string | No | (default: null) |
| includeSequences | boolean | No | (default: false) |
getPipelineRunRead-onlyGet one pipeline run's status and per-step progress. Poll this to follow a run submitted with submitPipeline.
| Parameter | Type | Required | Description |
|---|---|---|---|
| runId | string | Yes |
getPipelineRunResultsRead-onlyRead a pipeline run's OUTPUTS — the molecules each step produced, with their scores — rather than just its status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| runId | string | Yes | |
| node | string | No | (default: null) |
| limit | integer | No | (default: 25) |
| cursor | string | No | (default: null) |
getPipelineSchemaRead-onlyGet the pipeline IR schema and the full authoring guide. Call this BEFORE writing a `pipeline` graph for submitPipeline/validatePipeline — the IR has rules that are not guessable, and authoring blind reliably produces graphs the API rejects.
No parameters.
getPipelineTemplateRead-onlyGet one pipeline template: its graph, its bindable inputs, and its versions.
| Parameter | Type | Required | Description |
|---|---|---|---|
| templateId | string | Yes | |
| version | string | No | (default: null) |
getResultRead-onlyRetrieve results for a completed job
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | Yes | Name of the job to get results for |
| jobEmail | string | No | Email of another member of your team (optional) |
| fileName | string | No | Path to a specific file in the job results (optional) |
| pdbsOnly | boolean | No | Return only PDB files (optional) |
listJobFilesRead-onlyList all files in a job's S3 directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | Yes |
listModalitiesRead-onlyList the biological MODALITIES (molecule types) you can filter tools by.
No parameters.
listPipelineRunsRead-onlyList pipeline runs. Note that pipeline runs do NOT appear in getJobs() — that endpoint covers single jobs and batches only, so this is the way to see them.
| Parameter | Type | Required | Description |
|---|---|---|---|
| status | string | No | (default: null) |
| templateId | string | No | (default: null) |
| owner | string | No | (default: null) |
| limit | integer | No | (default: 50) |
| cursor | string | No | (default: null) |
listPipelineTemplatesRead-onlyList saved pipeline templates you can run. Use this to find an existing pipeline instead of authoring a graph from scratch — then read it with getPipelineTemplate() and run it with submitPipeline(templateId=...).
| Parameter | Type | Required | Description |
|---|---|---|---|
| search | string | No | (default: null) |
| owner | string | No | (default: null) |
| isPublished | boolean | No | (default: null) |
| limit | integer | No | (default: 50) |
| cursor | string | No | (default: null) |
listTagsRead-onlyList the FUNCTIONS (a.k.a. tags) you can filter tools by.
No parameters.
validateJobRead-onlyValidate a job's settings BEFORE submitting, so you can catch missing or invalid fields and fix them (or ask the user) instead of submitting and surfacing a 400.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | Yes | |
| type | string | Yes | |
| settings | object | Yes |
validatePipelineRead-onlyValidate a pipeline run WITHOUT executing or saving anything. ALWAYS call this before submitPipeline — a pipeline run costs real compute, and most authoring mistakes are caught here.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | |
| bindings | object | Yes | |
| pipeline | object | No | (default: null) |
| templateId | string | No | (default: null) |
| version | string | No | (default: null) |
| settings | object | No | (default: null) |
Write - Create new jobs, batches, or files.
submitBatchWriteSubmit MANY jobs as a SINGLE batch (one tool call, not one per job).
| Parameter | Type | Required | Description |
|---|---|---|---|
| batchName | string | Yes | |
| type | string | Yes | |
| settings | array | No | (default: null) |
| jobNames | array | No | (default: null) |
| fromJob | string | No | (default: null) |
| fromFile | string | No | (default: null) |
| sequenceField | string | No | (default: "sequence") |
| topN | integer | No | (default: null) |
| sharedSettings | object | No | (default: null) |
| maxRuntimeSeconds | integer | No | (default: null) |
| weightedHoursBudget | number | No | (default: null) |
submitJobWriteSubmit ONE job for protein analysis using one of the available tools.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | Yes | Unique name for the job |
| type | string | Yes | Tool to use for the job. IMPORTANT: Use getAvailableTools() to discover available tools dynamically. Tool list is updated frequently - do not rely on hardcoded values. Example workflow: 1. Call getAvailableTools(search="alphafold") to find tools 2. Call getJobSchema(jobType="alphafold") to get parameter schema 3. Call submitJob with the tool name and settings |
| settings | object | Yes | Job-specific settings. Structure depends on job type. IMPORTANT: Use the getJobSchema tool to get the exact parameter schema for your job type. Example: getJobSchema(jobType="proteinmpnn") returns the detailed schema with all parameters. Documentation: https://app.tamarind.bio/api-docs |
submitPipelineWriteRun a multi-tool pipeline. This SPENDS COMPUTE — call validatePipeline on the same graph and bindings first, and only submit once it reports valid:true.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | |
| bindings | object | Yes | |
| pipeline | object | No | (default: null) |
| templateId | string | No | (default: null) |
| version | string | No | (default: null) |
| settings | object | No | (default: null) |
| runName | string | No | (default: null) |
| project | string | No | (default: null) |
| idempotencyKey | string | No | (default: null) |
Destructive - Delete, cancel, or overwrite existing data.
cancelBatchDestructiveSoft-stop every member of a batch or pipeline in one call. Flips JobStatus to "Stopped" on all batch children, all pipeline stages, and the pipeline parent row (if one exists). Doesn't delete rows or outputs.
| Parameter | Type | Required | Description |
|---|---|---|---|
| batchName | string | Yes | Batch or pipeline name — same value used as `batchName` for submit-batch or `pipeline_name` for buildPipeline. |
cancelJobDestructiveSoft-stop a job — flips JobStatus to "Stopped" (same value the website cancel button writes) without deleting the row or outputs. Only works on jobs in "In Queue", "Running", or "Pending" status; jobs already in a terminal state are rejected with 400.
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | No | Name of the job to cancel (preferred input). |
| jobId | string | No | DDB row Id (alternative input, use if already known). |
deleteFileDestructiveDelete a workspace file (or a whole folder) from your Tamarind account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| filePath | string | No | (default: null) |
| folder | string | No | (default: null) |
deleteJobDestructivePermanently delete a job by name (if it's a batch, all of its subjobs are deleted too).
| Parameter | Type | Required | Description |
|---|---|---|---|
| jobName | string | Yes |
stopPipelineRunDestructiveStop a running pipeline. Steps that already finished keep their outputs; work still in flight is cancelled.
| Parameter | Type | Required | Description |
|---|---|---|---|
| runId | string | Yes |
uploadFileDestructiveUpload a local file to your Tamarind file store (up to 200 MB).
| Parameter | Type | Required | Description |
|---|---|---|---|
| filename | string | Yes | |
| content | string | No | (default: "") |
| encoding | string | No | (default: "text") |
| contentType | string | No | (default: "application/octet-stream") |
Each tool corresponds to the REST API endpoints documented in our API reference. Use the sidebar to explore each endpoint in detail.
Troubleshooting
Connector not appearing
- Save configuration file in the correct location and restart your client
- Verify JSON syntax is correct (no missing commas or brackets)
Authentication failing
- Verify your credentials (OAuth client ID/secret or API key) are correct and active
- For API key: ensure the key is passed via the
x-api-keyheader - For OAuth: log in with your Tamarind account and try again if a timeout occurs
Changes not applying
- Save the file, then completely quit and restart your client (not just refresh)
Tools not working
- Verify your authentication is still valid and try reconnecting
Requests to the MCP host blocked (403, or file uploads fail)
Sandboxed clients (Claude.ai, Claude Desktop) block outbound network by default. The MCP connection still works - it rides the client's connector - but the assistant's own requests to mcp.tamarind.bio are blocked, which shows up as a 403 or a file upload that fails with "network unreachable" / HTTP 000. It is not an authentication failure (those return 401). Allow the domain's egress:
- Claude Desktop / Claude.ai: Settings → Capabilities → enable Allow network egress → under Additional allowed domains add
mcp.tamarind.bio, then retry. - Small files (≤ 4 MB) can be uploaded inline by the assistant without enabling egress.
Need help? Contact us at info@tamarind.bio