SynVectorDB — MCP Server (stdio)

A lightweight MCP (Model Context Protocol) server exposing SynVectorDB APIs as MCP tools. It enables AI assistants (Claude Desktop, MCP-enabled IDEs, etc.) to query synthetic biology parts, run semantic search, and fetch dataset statistics from a Cloudflare-backed service.

• Protocol: Model Context Protocol — https://modelcontextprotocol.io/
• Default backend: https://testsdb.sjtu.bio
• Transport: stdio (works with npx synvectordb)

MCP config (copy & paste)

{
  "mcpServers": {
    "synvectordb": {
      "command": "npx",
      "args": ["synvectordb"],
      "env": {
        "SVD_BASE_URL": "https://testsdb.sjtu.bio"
      }
    }
  }
}

Quick Start

You only need Node.js ≥ 18.17. No installation is required to try it.

# Run the MCP server via npx (stdio mode)
npx synvectordb

# Optional: specify backend base URL (default shown)
SVD_BASE_URL=https://testsdb.sjtu.bio npx synvectordb

# Only required if you plan to call the admin tool (not needed for queries)
SVD_ADMIN_TOKEN=your_admin_token npx synvectordb

Configure in an MCP Client (e.g., Claude Desktop)

{
  "mcpServers": {
    "synvectordb": {
      "command": "npx",
      "args": ["synvectordb"],
      "env": {
        "SVD_BASE_URL": "https://testsdb.sjtu.bio"
        // "SVD_ADMIN_TOKEN": "${env:SVD_ADMIN_TOKEN}" // only needed for the admin tool
      }
    }
  }
}

Tools Overview

All tools return a single content item:

• JSON tools → { type: "json", text: "...json-string..." }
• FASTA tool → { type: "text", text: ">header\nSEQUENCE\n" }

stats

• Input: {}
• Output: summary JSON including totals, categories, sub_types, sources, histograms (length_histogram, gc_histogram), and updated_at.

search_parts

• Input:

{
  "page": 1,
  "page_size": 20,
  "name": "optional",
  "type_level_1": "optional",
  "type_level_2": "optional",
  "source_collection": "optional"
}

• Output: { parts, total_count, page, page_size }

semantic_search

• Input:

{
  "query": "promoter",
  "top_k": 10,
  "namespace": "optional",
  "type_level_1": "optional",
  "type_level_2": "optional",
  "source_collection": "optional"
}

• Output: { engine, count, matches }

get_part

• Input: { "uid": "<UID>" }
• Output: part detail JSON

get_sequence_fasta

• Input: { "uid": "<UID>" }
• Output: FASTA text

admin_upsert_vectors_sample (admin-only)

• Input: { "limit": 200, "offset": 0 }
• Requires SVD_ADMIN_TOKEN → sent as X-Admin-Token header
• Output: { ok, upserted, ... } or { ok:false, error }

Error Handling

• Network/HTTP errors are surfaced with status and raw body, e.g. HTTP 500: ....
• Invalid JSON responses are reported as Invalid JSON response: <snippet>.
• Unknown tool names return JSON-RPC error -32601.

Environment Variables

• SVD_BASE_URL
  • Default: https://testsdb.sjtu.bio
  • Change this to point to another deployment.
• SVD_ADMIN_TOKEN (optional)
  • Only needed for the admin tool admin_upsert_vectors_sample.
  • Do not set it unless you explicitly plan to use the admin operation.

Programmatic Client (Optional)

You can import and use the HTTP client in your own Node.js scripts.

import { SynVectorClient } from "synvectordb/dist/svd-client.js";

const client = new SynVectorClient(process.env.SVD_BASE_URL || "https://testsdb.sjtu.bio", process.env.SVD_ADMIN_TOKEN);
const stats = await client.getStats();
console.log(stats.total_parts);

Security Notes

• Query tools (stats, search_parts, semantic_search, get_part, get_sequence_fasta) do NOT require a token.
• The admin tool requires a server-side token; the server sends it as X-Admin-Token.
• Never commit tokens or .npmrc with auth entries to source control.

Versioning & License

• Versioning: SemVer-ish; patch releases may refine docs and non-breaking behavior.
• License: MIT © 2025