MCP Server

Overview

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

Once configured, agents can use the same public API surface as the web UI for jobs, datasets, projects, and account info. Agents will be instructed to use pre-signed URLs instead of auth file downloads.

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 is supported for remote MCP clients that use CIMD/OAuth discovery. In most clients, add the MCP URL https://subseq.bio/mcp, then complete the browser sign-in and authorization flow. No OAuth client ID or client secret needs to be copied from SubSeq.

Existing bearer-token auth is still supported: send Authorization: Bearer <api_key>.

1. Click your email (top-right) in the UI.
2. Open API Keys.
3. Click New Key.
4. Save it locally as SUBSEQ_API_KEY.

Client Config Examples

ChatGPT / Claude OAuth

Use the MCP server URL https://subseq.bio/mcp. The client should discover OAuth metadata, open SubSeq in the browser, and return to the client after authorization.

Claude Code

claude mcp add --transport http subseq https://subseq.bio/mcp --scope subseq: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 subseq https://subseq.bio/mcp --header "Authorization: Bearer ${SUBSEQ_API_KEY}"

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)

Command Palette -> "MCP" -> Open MCP Settings -> New MCP Server. Use the following mcp.json:

{
  "mcpServers": {
    "subseq": {
      "url": "https://subseq.bio/mcp",
      "headers": {
        "Authorization": "Bearer <your_subseq_api_key>"
      }
    }
  }
}

Tools, Resources, and Downloads

Tools mirror the public REST API (jobs, datasets, projects, account info, pricing, status). Use tools/list for the full set.

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 usage help, call program_usage for raw program flags, or browse resources under subseq://usage/tools/<tool> and subseq://usage/programs/<program>.

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.

Protocol Compatibility

The server implements MCP HTTP transport with one JSON-RPC 2.0 request per POST. The MCP-Protocol-Version header is optional; the server replies with the negotiated version.

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