turbopuffer-mcp

A Turbopuffer MCP server built with dedalus-mcp and DAuth-style credential exchange.

This server follows the same DAuth north-star pattern as x-api-mcp:

• Credentials are provided by clients at runtime.
• The server declares a Connection with SecretKeys.
• Tool calls dispatch through Dedalus secure connection handles.

Features

• DAuth-compatible API key authentication (TURBOPUFFER_API_KEY).
• Configurable Turbopuffer region/base URL via TURBOPUFFER_BASE_URL.
• Read + write tool coverage for the core Turbopuffer API.
• Includes a smoke ping tool for quick MCP handshake validation.

Setup

1. Create a Turbopuffer API key.
2. Copy env template:

cp .env.example .env

Required:

• TURBOPUFFER_API_KEY (provided by the MCP client via DAuth credentials in production flows)

Optional:

• TURBOPUFFER_BASE_URL (defaults to https://gcp-us-central1.turbopuffer.com)
• DEDALUS_AS_URL (defaults to https://as.dedaluslabs.ai)
• HOST (defaults to 127.0.0.1)
• PORT (defaults to 8080)

Run

uv run python src/main.py

Tool Surface

• turbopuffer_list_namespaces
• turbopuffer_get_namespace_metadata
• turbopuffer_get_namespace_schema
• turbopuffer_update_namespace_schema
• turbopuffer_write
• turbopuffer_query
• turbopuffer_multi_query
• turbopuffer_explain_query
• turbopuffer_delete_namespace
• turbopuffer_cache_warm
• turbopuffer_measure_recall
• turbopuffer_export_documents (deprecated Turbopuffer endpoint compatibility)
• smoke_ping

Notes

• Turbopuffer has both /v1 and /v2 endpoints. This server mirrors the live docs/API split:
  • Namespace listing/metadata/schema/cache-warm/recall/export use /v1.
  • Write/query/delete/explain use /v2.
• The export endpoint is deprecated in Turbopuffer docs in favor of paging query APIs, but is still exposed here for compatibility.