MCP Server

Overview

Endpoint: https://subseq.bio/mcp (HTTP transport, JSON-RPC 2.0 over POST).

The MCP server exposes tools for compute programs, jobs, pipelines, datasets, projects, account info, pricing, and status. It exposes a subset of the public REST API; discover the available tools with tools/list. Use presigned URLs for bulk file transfers.

Note: This allows agents to autonomously delete data and use your account credits. The MCP server is experimental with ongoing improvements. Use carefully.

Authentication

OAuth requires a client that supports Client ID Metadata Documents (CIMD), with an HTTPS metadata URL as its client ID, and authorization code flow with PKCE S256. Add https://subseq.bio/mcp, then complete browser sign-in and authorization. SubSeq does not provide dynamic client registration or a client secret. Clients without CIMD support should use an API key.

For API-key authentication, send Authorization: Bearer <api_key>. Use a standard client API key; login/admin keys are rejected by MCP.

1. Click your email (top-right) in the UI.
2. Open API Keys.
3. Click New Key. Choose read/write access to submit jobs or change data, or read-only access for inspection and downloads. Optionally restrict the key to a project.
4. Save the key securely. For the CLI examples below, set SUBSEQ_API_KEY in the environment of the process running your agent.

API keys retain their account/team and project restrictions. To work in a team, create a key in that team context; see Teams. OAuth currently grants read/write access to your personal account across projects. OAuth tokens are valid for 30 days; sign in again after expiry. Revoke them under API Keys → OAuth Tokens.

Client Config Examples

Remote clients with OAuth

Use https://subseq.bio/mcp with OAuth in a CIMD-capable client. The requested OAuth scope is subseq:mcp. Client versions and account settings determine whether remote MCP connections are available.

Claude Code

claude mcp add --transport http --scope user subseq https://subseq.bio/mcp
# In Claude Code, run /mcp and authenticate when prompted.

Claude Code (API key)

export SUBSEQ_API_KEY='<your_subseq_api_key>'
claude mcp add --transport http --scope user --header "Authorization: Bearer ${SUBSEQ_API_KEY}" subseq https://subseq.bio/mcp

--scope user controls where Claude Code saves the configuration; it is not an OAuth scope. The API-key command stores the expanded key in your local Claude configuration.

Codex

codex mcp add subseq --url https://subseq.bio/mcp
codex mcp login subseq --scopes subseq:mcp

Codex (API key)

export SUBSEQ_API_KEY='<your_subseq_api_key>'
codex mcp add subseq --url https://subseq.bio/mcp --bearer-token-env-var SUBSEQ_API_KEY

Cursor (API key)

Add this configuration to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Make SUBSEQ_API_KEY available to the Cursor process:

{
  "mcpServers": {
    "subseq": {
      "url": "https://subseq.bio/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SUBSEQ_API_KEY}"
      }
    }
  }
}

For Codex and Cursor, the key must remain available in the agent process environment; exporting it in an unrelated terminal does not update an already-running app. Choose one authentication method per server entry. See the current Claude Code, Codex, and Cursor client documentation.

Tools, Resources, and Downloads

Use tools/list for current tool names and input schemas. Tool names below are the server names; clients may display them with a server prefix.

Purpose	Tools
Discovery and account	get_status, program_list, program_params, program_usage, get_pricing, account_info
Jobs	job_submit, job_submit_advanced, job_list, job_info, job_cancel, job_move_project
Pipelines	pipeline_submit, pipeline_list, pipeline_info
Datasets	dataset_new, dataset_edit, dataset_upload_presign, dataset_list, dataset_info, dataset_delete, dataset_rename, dataset_move_project
Files	manifest_list, read_file, get_presigned_url
Projects	project_new, project_list, project_rename, project_delete
Credit purchases	x402_topup

Start with program_list, optionally passing q (for example, {"q":"fold"}) to find programs by name, aliases, or description. Load parameters or usage only for the program you need. Resource descriptions summarize each tool and program so clients can select relevant help before reading it.

Inspect outputs with job_info or dataset_info, then manifest_list and read_file. Paginated list tools and read_file return next_offset and more_available; always follow those values because byte limits can shorten a page. Use get_presigned_url for bulk downloads.

x402_topup adds credits with USDC on Base. It requires an x402-aware MCP HTTP transport: the first tool call receives 402 Payment Required, then the client retries with PAYMENT-SIGNATURE. Bearer authentication is still required so the credits attach to the correct SubSeq account.

For job submission, call program_params to inspect typed parameters, then submit with job_submit. If guided=false, or you need raw arguments and auxiliary mounts, read program_usage and use job_submit_advanced. You can also browse resources under subseq://usage/tools/<tool> and subseq://usage/programs/<program>.

Use project_list to select an existing project, or project_new to create one. Dataset creation requires an existing project; the name default in examples is not created automatically. Pipelines accept a shared dataset or no input through MCP; see Pipelines.

File uploads via MCP are intended for small inputs only (the file bytes must be included directly in the tool call). MCP upload limits: up to 256 files, up to 2 MiB total, up to 512 KiB per file. For large folders/files, use dataset_upload_presign to mint a temporary upload URL, curl a ZIP archive to create a dataset, then mount it via input_src="dataset".

Dataset names should be short human labels without dates or timestamps. Creation time is already tracked in created_at.

For dataset_upload_presign, ZIP uploads strip one common top-level wrapper directory when all files share it; otherwise archive-relative paths are preserved.

Building Your Own Agent

Use an MCP SDK with Streamable HTTP support and the endpoint above. Authenticate every request, including initialization and discovery. No local SubSeq server process is needed. A read-only connection check:

curl --fail-with-body https://subseq.bio/mcp \
  -H "Authorization: Bearer ${SUBSEQ_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

After initialization, send notifications/initialized without an id, then discover tools with tools/list. For example, send this JSON body to call a tool:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"program_list","arguments":{"q":"fold"}}}

Examples in tool help show the params object (name and arguments), not the full JSON-RPC request. Read help using resources/read with {"uri":"subseq://usage/tools/job_submit"}; use resources/list to discover available help. These resource URIs are MCP identifiers, not HTTP download URLs.

Tool results are returned as result.content[] text blocks. Most contain JSON text with the API data unwrapped; program_usage returns Markdown. Do not assume a REST success/data envelope or structuredContent. Check JSON-RPC error and tool-result isError: HTTP 200 alone does not mean the tool succeeded.

Submitting a job returns before computation finishes. Keep its job ID and poll job_info at intervals of at least 60 seconds until a terminal status such as completed, failed, or cancelled. If a submit request times out, inspect job_list before retrying to avoid duplicate paid jobs.

Troubleshooting

• 401: check the bearer header, the agent process environment, and whether the key or OAuth token expired or was revoked.
• 403 or a permission error: MCP rejects login/admin keys. Check read/write access, project restrictions, and the account/team associated with the key.
• OAuth registration or client-ID error: use a CIMD-capable client or API-key authentication. SubSeq has no dynamic client registration endpoint.
• 405 from GET /mcp: this is expected. The endpoint accepts POST requests and does not provide an SSE stream over GET.
• 429: back off before retrying; avoid rapid polling.
• Missing files: info responses contain manifest previews. Use manifest_list for exact paths and read_file for bounded text, or download using get_presigned_url.

Protocol Compatibility

The server accepts one JSON-RPC 2.0 request per POST and returns JSON. It does not support JSON-RPC batches, GET/SSE streams, or session IDs. Initialization returns the negotiated protocol version; use it in MCP-Protocol-Version on subsequent requests. If that header is omitted, this server defaults to 2025-06-18. Notifications return HTTP 202 with no body.

Server identifier: subseq-mcp v0.3.1. tools/resources listChanged notifications are not emitted.