MCP Tool Reference

create_analytics_cube

Create a named OLAP cube backed by a fact table with specified dimensions and measures. The cube is persisted and can be queried repeatedly with different aggregations.

{"success": true, "cube_name": "sales_cube", "fact_table": "sales", "dimensions": ["region", "product"], "measures": ["revenue"]}

create_analytics_cube(
  cube_name="sales_cube",
  fact_table="sales",
  dimensions=["region", "product", "quarter"],
  measures=["revenue", "units_sold"]
)

query_analytics

Query an OLAP cube with optional dimension grouping, measure selection, and filter predicates. Returns aggregated results with execution metadata.

{"results": [{"region": "EMEA", "revenue": 4200000}], "count": 1, "execution_time": 0.043, "cache_hit": false}

query_analytics(
  cube_name="sales_cube",
  dimensions=["region"],
  measures=["revenue"],
  filters={"quarter": "Q4"}
)

delete_analytics_cube

Permanently delete a named OLAP cube and all associated metadata.

{"deleted": true, "cube_name": "sales_cube"}

delete_analytics_cube(cube_name="sales_cube")

store_blob

Store arbitrary binary content (base64-encoded) with optional filename, MIME type, and metadata. Returns a unique blob ID for later retrieval.

{"blob_id": "blob_a1b2c3d4", "filename": "report.pdf", "mime_type": "application/pdf", "size": 204800}

store_blob(
  content="JVBERi0xLjQK...",   # base64
  filename="report.pdf",
  mime_type="application/pdf",
  metadata={"owner": "alice", "project": "Q4"}
)

get_blob

Retrieve a stored blob by its ID. Returns the base64-encoded content, associated metadata, byte size, and content hash for integrity verification.

{"content": "JVBERi0xLjQK...", "metadata": {"owner": "alice"}, "size": 204800, "content_hash": "sha256:abc..."}

get_blob(blob_id="blob_a1b2c3d4")

delete_blob

Permanently delete a blob by its ID.

{"deleted": true, "blob_id": "blob_a1b2c3d4"}

delete_blob(blob_id="blob_a1b2c3d4")

store_document

Store a JSON document in a named collection. If no document_id is provided, one is auto-generated. Documents are stored with full JSON fidelity and are queryable via filter expressions.

{"document_id": "doc_x7y8z9"}

store_document(
  collection="users",
  document={"name": "Alice", "role": "admin", "active": true},
  document_id="user_alice"
)

search_documents

Query documents in a collection using a filter expression. Supports equality, range, and nested field filters. Returns matching documents up to the specified limit.

{"documents": [{"_id": "user_alice", "name": "Alice", "role": "admin"}], "count": 1}

search_documents(
  collection="users",
  filter={"role": "admin", "active": true},
  limit=50
)

get_document

Retrieve a single document by its exact ID from a collection.

{"document": {"_id": "user_alice", "name": "Alice", "role": "admin", "active": true}}

get_document(collection="users", document_id="user_alice")

delete_document

Delete a single document by ID from a collection.

{"deleted": true, "document_id": "user_alice"}

delete_document(collection="users", document_id="user_alice")

index_fulltext

Add or update a document in a full-text search index. The index is created automatically on first use. Uses BM25 ranking for retrieval.

{"success": true, "index_name": "articles", "doc_id": "article_001"}

index_fulltext(
  index_name="articles",
  doc_id="article_001",
  document="PolyDB supports 16 data models with pluggable backends."
)

search_fulltext

Search a full-text index using BM25 relevance ranking. Supports multi-word queries with implicit AND semantics.

{"results": [{"id": "article_001", "score": 0.92, "snippet": "..."}], "count": 1, "query": "pluggable backends"}

search_fulltext(index_name="articles", query="pluggable backends", limit=5)

delete_fulltext

Remove a document from a full-text search index by its document ID.

{"deleted": true, "index_name": "articles", "doc_id": "article_001"}

delete_fulltext(index_name="articles", doc_id="article_001")

add_graph_node

Add a node to the graph with optional typed properties. Nodes are identified by a unique string ID. If the node already exists, its properties are updated.

{"node_id": "user_alice", "success": true}

add_graph_node(
  node_id="user_alice",
  node_type="Person",
  properties={"name": "Alice", "department": "Engineering"}
)

add_graph_edge

Add a directed edge between two existing nodes. The edge may carry a type label and arbitrary properties.

{"edge_id": "edge_abc123", "success": true}

add_graph_edge(
  from_node="user_alice",
  to_node="user_bob",
  edge_type="KNOWS",
  properties={"since": "2024-01-01"}
)

query_graph

Traverse the graph starting from a node using a named pattern. Supported patterns include "neighbors", "shortest_path", and "subgraph". Depth controls traversal levels.

{"results": [{"node_id": "user_bob", "distance": 1}], "pattern": "neighbors", "depth": 1}

query_graph(start_node="user_alice", pattern="neighbors", depth=2)

delete_graph_node

Delete a node and all its incident edges from the graph.

{"deleted": true, "node_id": "user_alice"}

delete_graph_node(node_id="user_alice")

delete_graph_edge

Delete a specific edge by its ID.

{"deleted": true, "edge_id": "edge_abc123"}

delete_graph_edge(edge_id="edge_abc123")

create_iceberg_table

Create an Apache Iceberg-format table with a declared schema, optional partition spec, and table properties. Supports schema evolution and time-travel queries.

{"table_id": "tbl_001", "table_name": "events"}

create_iceberg_table(
  table_name="events",
  schema={"id": "long", "ts": "timestamp", "event_type": "string", "payload": "string"},
  partition_by=["event_type"]
)

append_iceberg

Append a batch of records to an Iceberg table. Each append creates an immutable snapshot that can be queried independently for time-travel.

{"snapshot_id": "snap_20240101_001", "record_count": 1000}

append_iceberg(
  table="events",
  data_records=[
    {"id": 1, "ts": "2024-01-01T00:00:00Z", "event_type": "click", "payload": "{}"},
    {"id": 2, "ts": "2024-01-01T00:00:01Z", "event_type": "view",  "payload": "{}"}
  ]
)

get_iceberg_snapshot_as_of

Time-travel query: retrieve the state of an Iceberg table as it existed at a specific timestamp. Useful for auditing, reproducibility, and debugging.

{"snapshot_id": "snap_20240101_001", "timestamp": "2024-01-01T12:00:00Z", "records": [...]}

get_iceberg_snapshot_as_of(table="events", timestamp="2024-01-01T12:00:00Z")

add_iceberg_column

Add a new column to an existing Iceberg table schema. Existing snapshots are unaffected; the new column returns null for rows predating the schema change.

{"table": "events", "column_name": "user_id", "column_type": "string"}

add_iceberg_column(table="events", column_name="user_id", column_type="string")

expire_iceberg_snapshots

Remove old snapshots from an Iceberg table to reclaim storage, retaining only the most recent N snapshots. The latest snapshot is always retained.

{"table": "events", "retain_last_n": 5}

expire_iceberg_snapshots(table="events", retain_last_n=5)

set_keyvalue

Store any JSON-serialisable value under a key in a namespace. Supports optional TTL (seconds) for automatic expiry.

{"success": true, "key": "session:abc", "namespace": "sessions", "ttl": 3600}

set_keyvalue(key="session:abc", value={"user_id": 42}, namespace="sessions", ttl=3600)

get_keyvalue

Retrieve the value associated with a key in a namespace. Returns null value if the key does not exist or has expired.

{"key": "session:abc", "namespace": "sessions", "value": {"user_id": 42}}

get_keyvalue(key="session:abc", namespace="sessions")

delete_keyvalue

Delete a key-value pair from a namespace.

{"deleted": true, "key": "session:abc", "namespace": "sessions"}

delete_keyvalue(key="session:abc", namespace="sessions")

list_keyvalues

List all non-expired keys in a namespace.

{"keys": ["session:abc", "session:def"], "count": 2, "namespace": "sessions"}

list_keyvalues(namespace="sessions")

store_memory

Persist an agent interaction (input + response pair) to long-term memory. The interaction is vectorised and stored with session context for later semantic retrieval.

{"memory_id": "mem_001", "interaction_id": "int_001", "vector_id": "vec_001", "session_id": "sess_abc"}

store_memory(
  user_input="What is PolyDB?",
  llm_response="PolyDB is a multi-model database...",
  session_id="sess_abc",
  interaction_type="conversation"
)

recall_memory

Retrieve relevant memory context using semantic similarity search. Optionally filter by session and interaction types. Returns ranked context items for injection into prompts.

{"context_items": [{"memory_id": "mem_001", "score": 0.91, "content": "..."}], "total_items": 1}

recall_memory(query="multi-model database", session_id="sess_abc", max_items=5)

delete_memory

Delete a stored memory interaction by its ID.

{"deleted": true, "memory_id": "mem_001"}

delete_memory(memory_id="mem_001")

store_knowledge

Store a structured knowledge item with type classification, source provenance, and confidence score. Knowledge is vectorised and indexed for semantic retrieval.

{"knowledge_id": "know_001", "content_length": 120, "knowledge_type": "factual"}

store_knowledge(
  content="PolyDB supports 16 data models including Vector, Graph, and Time Series.",
  knowledge_type="factual",
  source="https://polydb.dev/docs",
  confidence=1.0
)

search_knowledge

Semantically search stored knowledge items by query, filtered by knowledge type and minimum confidence threshold.

{"results": [{"knowledge_id": "know_001", "score": 0.95, "content": "..."}], "total_results": 1}

search_knowledge(query="data models", knowledge_types=["factual"], min_confidence=0.8, limit=5)

delete_knowledge

Delete a stored knowledge item by its ID.

{"deleted": true, "knowledge_id": "know_001"}

delete_knowledge(knowledge_id="know_001")

create_bucket

Create an S3 bucket. Idempotent — safe to call even if the bucket already exists. Call this first; every other S3 tool depends on a bucket existing.

{"created": true, "bucket": "my-bucket", "region": "us-east-1"}

{"created": false, "already_existed": true, "bucket": "my-bucket", "region": "us-east-1"}

create_bucket(bucket="my-bucket")

put_s3_object

Upload an object to a named S3-compatible bucket. The content is stored as-is with the specified content type. The bucket must already exist — call create_bucket first.

{"success": true, "bucket": "my-bucket", "key": "data/report.json", "size": 1024}

put_s3_object(
  bucket="my-bucket",
  key="data/report.json",
  content="{\"total\": 42}",
  content_type="application/json"
)

get_s3_object

Retrieve an object from a bucket by key.

{"content": "{\"total\": 42}", "content_type": "application/json", "content_length": 13}

get_s3_object(bucket="my-bucket", key="data/report.json")

list_s3_objects

List objects in a bucket, optionally filtered by key prefix.

{"objects": [{"key": "data/report.json", "size": 1024, "last_modified": "2024-01-01T00:00:00Z"}], "count": 1, "bucket": "my-bucket"}

list_s3_objects(bucket="my-bucket", prefix="data/")

delete_s3_object

Delete an object from a bucket.

{"deleted": true, "bucket": "my-bucket", "key": "data/report.json"}

delete_s3_object(bucket="my-bucket", key="data/report.json")

delete_bucket

Delete an S3 bucket. The bucket must be empty before deletion. Delete all objects first with delete_s3_object, then call this tool.

{"success": true, "bucket": "my-bucket"}

delete_bucket(bucket="my-bucket")

list_buckets

List all S3 buckets belonging to the authenticated tenant. Bucket names are tenant-scoped — each tenant's buckets are isolated from other tenants.

{"buckets": [{"name": "my-bucket", "created_at": "2026-04-29T12:00:00Z"}], "count": 1}

list_buckets()

store_spatial

Store a geospatial geometry (GeoJSON or WKT string) in a named spatial table along with arbitrary attribute data.

{"feature_id": "feat_001", "table_name": "locations"}

store_spatial(
  table_name="locations",
  geometry={"type": "Point", "coordinates": [-0.1278, 51.5074]},
  attributes={"name": "London HQ", "category": "office"}
)

search_spatial_nearby

Find spatial features within a given radius of a point. Results are ordered by distance.

{"results": [{"feature_id": "feat_001", "distance": 234.5, "attributes": {...}}], "count": 1, "search_point": {"longitude": -0.1278, "latitude": 51.5074}}

search_spatial_nearby(
  table_name="locations",
  longitude=-0.1278,
  latitude=51.5074,
  radius_meters=1000,
  limit=20
)

search_spatial_bbox

Find spatial features that intersect or fall within a bounding box defined by min/max longitude and latitude coordinates.

{"results": [{"feature_id": "feat_001", "attributes": {...}}], "count": 1, "bbox": [-0.15, 51.49, -0.10, 51.52]}

search_spatial_bbox(
  table_name="locations",
  min_lon=-0.15, min_lat=51.49,
  max_lon=-0.10, max_lat=51.52
)

delete_spatial

Delete a spatial feature from a table by its feature ID.

{"deleted": true, "feature_id": "feat_001"}

delete_spatial(table_name="locations", feature_id="feat_001")

query_sql

Execute a read-only SQL statement against the underlying backend. Only SELECT, WITH (CTEs), EXPLAIN, and SHOW statements are permitted. Write operations are rejected. Parameterised queries are recommended to prevent injection. Parameters use ? placeholders — PostgreSQL-style $1/$N syntax is not supported. Queries against pg_* and information_schema system tables are also rejected.

{"rows": [{"id": 1, "name": "Alice"}], "columns": ["id", "name"], "count": 1}

query_sql(
  query="SELECT id, name FROM users WHERE role = ?",
  params=["admin"]
)

publish_stream

Publish an event to a named stream. The event is appended to the stream log with a server-assigned sequence number and timestamp.

{"success": true, "stream_name": "user-events"}

publish_stream(
  stream_name="user-events",
  event_data={"type": "login", "user_id": 42, "ip": "1.2.3.4"}
)

consume_stream

Read and consume up to N events from a stream. Consumed events are removed from the head of the stream.

{"events": [{"event_id": "evt_001", "event_type": "login", "payload": {"type": "login"}, "timestamp": "2024-01-01T00:00:00Z", "ingested_at": "2024-01-01T00:00:00Z", "created_at": "2024-01-01T00:00:00Z", "sequence_id": 1}], "count": 1}

consume_stream(stream_name="user-events", limit=50)

store_temporal

Store a versioned snapshot of an entity. Each call creates a new immutable version. If no timestamp is provided, the current UTC time is used.

{"entity_id": "config:app", "version_id": "ver_003", "version_number": 3}

store_temporal(
  entity_id="config:app",
  data={"max_connections": 100, "timeout_ms": 5000},
  timestamp="2024-06-01T09:00:00Z"
)

query_temporal_at

Retrieve the state of an entity at a specific point in time. Returns the version whose timestamp is closest to and not after the requested time.

{"entity_id": "config:app", "timestamp": "2024-06-01T09:00:00Z", "data": {"max_connections": 100}}

query_temporal_at(entity_id="config:app", timestamp="2024-06-01T09:00:00Z")

query_temporal_history

Retrieve all versions of an entity between two timestamps, ordered chronologically.

{"history": [{"version": 2, "ts": "...", "data": {...}}, {"version": 3, "ts": "...", "data": {...}}], "count": 2}

query_temporal_history(
  entity_id="config:app",
  start_time="2024-01-01T00:00:00Z",
  end_time="2024-12-31T23:59:59Z"
)

store_timeseries

Record a single time-series data point for a named metric. Optionally attach tags for multi-dimensional filtering. If no timestamp is given, server time is used.

{"success": true, "metric": "cpu_percent", "value": 72.3}

store_timeseries(
  metric="cpu_percent",
  value=72.3,
  tags={"host": "web-01", "region": "eu-west"}
)

query_timeseries

Query a time-series metric over a time range with server-side aggregation. Supported aggregations: avg, sum, min, max, count.

{"results": [{"ts": "2024-01-01T00:00:00Z", "value": 68.4}], "count": 1, "metric": "cpu_percent"}

query_timeseries(
  metric="cpu_percent",
  start_time="2024-01-01T00:00:00Z",
  end_time="2024-01-01T01:00:00Z",
  aggregation="avg"
)

store_vector

Store a dense embedding vector in a named collection. Attach metadata for filtering during similarity search. If no vector_id is provided, one is auto-generated.

{"vector_id": "vec_001"}

store_vector(
  collection="documents",
  vector=[0.021, -0.045, 0.103, ...],  # 1536 floats
  metadata={"doc_id": "article_001", "source": "blog"}
)

search_vectors

Find the K nearest vectors to a query vector using pgvector. Returns vector IDs, distances, and attached metadata. Note: results use distance (lower is closer), not a score field — this follows the pgvector convention.

{"results": [{"vector_id": "vec_001", "distance": 0.03, "metadata": {"doc_id": "article_001"}}], "count": 1}

search_vectors(
  collection="documents",
  query_vector=[0.021, -0.045, 0.103, ...],
  k=10
)

delete_vector

Delete a stored vector from a collection by its ID.

{"deleted": true, "vector_id": "vec_001"}

delete_vector(collection="documents", vector_id="vec_001")

execute_workflow Pro / Enterprise

Execute a multi-step workflow where each step calls a PolyDB tool. Steps can reference outputs from prior steps using $ref(step_id.field) to chain step outputs as inputs to later steps. All steps execute sequentially; the first failure stops the chain and is reported in errors. Available on Pro and Enterprise plans. Note: $embed(text) server-side embedding is coming soon.

{"results": {"step1": {"document_id": "doc_001"}, "step2": {"vector_id": "vec_001"}}, "completed": 2, "total": 2, "errors": []}

execute_workflow(steps=[
  {
    "id": "store_doc",
    "op": "store_document",
    "args": {"collection": "articles", "document": {"title": "Hello"}}
  },
  {
    "id": "store_vec",
    "op": "store_vector",
    "args": {
      "collection": "embeddings",
      "vector": [0.1, 0.2, 0.3],
      "metadata": {"doc_id": "$ref(store_doc.document_id)"}
    }
  }
])

search_schema

Discover all available tools and their signatures. Use this as a first call to understand what capabilities are available. Optionally filter by provider name or keyword.

{"tools": [{"name": "store_vector", "provider": "vector", "description": "..."}, ...], "total": 59, "filter_applied": null}

# Discover all tools
search_schema()

# Filter to vector-related tools
search_schema(filter="vector")

health_check

Health probe for the PolyDB MCP server. Returns service identity, version, and transport so a client can verify connectivity and version-pin its calls.

{"status": "healthy", "service": "polydb-mcp-server", "version": "0.9.x", "transport": "streamable-http"}

health_check()

list_databases

Read-only discovery tool that enumerates the databases available to the current tenant. The tenant’s default/current database is flagged with current: true. To create or delete databases, use the REST API at /api/databases — this MCP tool is read-only. A brand-new tenant whose default DB has not yet been materialized via the REST endpoint will see an empty list; call POST /api/databases first.

To target a specific database for a tool call, supply the database argument on the tool (e.g. store_document(..., database='analytics')), or set X-PolyDB-Database: <name> as a request header. To change the persistent default, use PATCH /api/databases/{name}/default.

{"databases": [{"name": "polydb", "current": true, "created_at": "2026-04-01T00:00:00+00:00"}, ...]}

list_databases()