MCP Server | TenantsDB

What is MCP

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources.

TenantsDB exposes 26 tools through an MCP server. AI clients like Claude Desktop, Claude.ai, Cursor, and any MCP-compatible app can discover and call these tools once connected via OAuth. Tool calls are authenticated with OAuth access tokens and scoped to the project the user approved.

Learn more about MCP at modelcontextprotocol.io. TenantsDB implements the Streamable HTTP transport per the MCP specification.

Server URL

One endpoint. Every MCP client connects here.

MCP Endpoint

https://api.tenantsdb.com/mcp

Clients discover the OAuth endpoints via RFC 9728 Protected Resource Metadata:

Discovery

GET https://api.tenantsdb.com/.well-known/oauth-protected-resource

Authentication

Every tool call is authenticated with an OAuth 2.0 access token.

Clients include a Bearer token on every request:

HTTP Header

Authorization: Bearer tdb_oat_...

Tokens expire after 1 hour. MCP clients refresh them automatically using the refresh token they received during OAuth. See Build an Integration for the OAuth flow.

Tool Annotations

Each tool declares metadata that helps AI clients reason about safety and behavior.

Annotation	Meaning
ReadOnlyHint	Tool does not modify any state. Safe to retry, safe to call without confirmation.
DestructiveHint	Tool performs irreversible changes. Client should confirm with the user before calling.
OpenWorldHint	Tool fetches data from the open internet. Results may be non-deterministic.

Workspaces

Tools for managing and inspecting workspaces.

READ list_workspaces

Returns all workspaces in the current project, including mode (tenant or control), database type, and creation date.

Input

No parameters.

Output

{
  "count": 2,
  "workspaces": [
    {
      "id": "orders",
      "name": "orders",
      "database": "PostgreSQL",
      "mode": "tenant",
      "version": "1.5",
      "created_at": "2026-04-06T06:56:20Z"
    }
  ]
}

READ get_workspace

Returns detailed info for one workspace, including the full schema with tables, columns, and constraints.

Input

Field	Type		Description
workspace_id	string	required	ID of the workspace.

Output

{
  "id": "orders",
  "database": "PostgreSQL",
  "mode": "tenant",
  "schema": {
    "tables": [
      {
        "name": "users",
        "columns": [
          { "name": "id", "data_type": "INTEGER", "constraint": "PRIMARY KEY" }
        ]
      }
    ]
  }
}

READ get_workspace_schema

Returns only the schema of a workspace. Same as get_workspace but without metadata. Useful when the AI just needs table structure.

Input

Field	Type		Description
workspace_id	string	required	ID of the workspace.

WRITE create_workspace

Creates a new workspace. Mode must be either tenant or control.

Input

Field	Type		Description
name	string	required	Unique workspace name within the project.
database	string	required	One of: `PostgreSQL`, `MySQL`, `MongoDB`, `Redis`.
mode	string	required	Either `tenant` or `control`.

READ get_workspace_diff

Returns the list of pending schema changes (DDLs) in a tenant workspace that have not yet been deployed to tenants.

Input

Field	Type		Description
workspace_id	string	required	ID of the tenant workspace.

WRITE query_workspace_dev

Runs a SQL or DDL query against the development workspace (not tenant data). Use this to design and test schema changes before deploying.

Input

Field	Type		Description
workspace_id	string	required	ID of the workspace.
query	string	required	SQL or DDL statement to execute.

Blueprints

Versioned schema snapshots that get deployed to tenants.

READ list_blueprints

Returns all blueprints in the project with their latest versions.

Input

No parameters.

Tenants

Isolated databases for your customers. One tenant per customer.

READ list_tenants

Returns all tenants, optionally filtered by blueprint.

Input

Field	Type		Description
blueprint	string	optional	Filter by blueprint name.

READ get_tenant

Returns full tenant details including status, isolation level, databases, and recovery info.

Input

Field	Type		Description
tenant_id	string	required	Tenant identifier.

WRITE create_tenant

Creates a new tenant and provisions its databases from the specified blueprints.

Input

Field	Type		Description
tenant_id	string	required	Unique tenant identifier.
databases	array	required	List of database configurations. Each must include `blueprint` and optional `isolation_level` (1 or 2).

WRITE suspend_tenant

Blocks all queries to a tenant. Data is preserved. Reversible with resume_tenant.

Input

Field	Type		Description
tenant_id	string	required	Tenant to suspend.

WRITE resume_tenant

Restores query access to a suspended tenant.

Input

Field	Type		Description
tenant_id	string	required	Tenant to resume.

WRITE create_backup

Triggers an on-demand backup for a tenant.

Input

Field	Type		Description
tenant_id	string	required	Tenant to back up.

READ list_backups

Returns all backups for a tenant with timestamps, sizes, and storage paths.

Input

Field	Type		Description
tenant_id	string	required	Tenant identifier.

READ get_tenant_logs

Returns recent query logs for a tenant. Useful for debugging and auditing.

Input

Field	Type		Description
tenant_id	string	required	Tenant identifier.
limit	integer	optional	Max entries to return (default 100).

READ get_tenant_metrics

Returns query volume, latency, and error counts for a tenant.

Input

Field	Type		Description
tenant_id	string	required	Tenant identifier.

Deployments

Deploying blueprint changes to tenants.

READ list_deployments

Returns recent deployments across all blueprints.

Input

No parameters.

READ get_deployment_status

Returns detailed status for one deployment job, including per-tenant progress.

Input

Field	Type		Description
deployment_id	string	required	ID returned by `deploy_blueprint`.

WRITE deploy_blueprint

Deploys the current version of a blueprint to one or more tenants. Returns a deployment job ID for progress tracking.

Input

Field	Type		Description
blueprint_name	string	required	Name of the blueprint to deploy.
tenant_ids	array	optional	Specific tenants. If omitted, deploys to all tenants running this blueprint.
version	string	optional	Specific version. Defaults to latest.

Data Queries

Query tenant data. DDL statements are blocked automatically.

WRITE query_tenant

Runs a query against one tenant's isolated database. Works for PostgreSQL, MySQL, MongoDB, and Redis.

Input

Field	Type		Description
blueprint	string	required	Blueprint name (identifies which database type).
tenant_id	string	required	Target tenant.
query	string	required	SQL, MongoDB command, or Redis command.

Example

Input

{
  "blueprint": "orders",
  "tenant_id": "acme",
  "query": "SELECT id, email, name FROM users WHERE role = 'admin' LIMIT 5"
}

WRITE query_all_tenants

Runs the same query across every tenant in a blueprint. Returns per-tenant results in one response. Useful for cross-tenant reporting.

Input

Field	Type		Description
blueprint	string	required	Blueprint to query across.
query	string	required	Query to run on every tenant.

Keyword and AI-powered search across tenant data.

READ search_tenant

Keyword search across one tenant's data.

Input

Field	Type		Description
blueprint	string	required	Blueprint name.
tenant_id	string	required	Target tenant.
query	string	required	Search query.

READ search_all_tenants

Keyword search across every tenant in a blueprint.

Input

Field	Type		Description
blueprint	string	required	Blueprint name.
query	string	required	Search query.

READ ai_search_tenant

Semantic (vector) search across one tenant's data.

Input

Field	Type		Description
blueprint	string	required	Blueprint name.
tenant_id	string	required	Target tenant.
query	string	required	Natural language query.

READ ai_search_all_tenants

Semantic search across every tenant in a blueprint.

Input

Field	Type		Description
blueprint	string	required	Blueprint name.
query	string	required	Natural language query.

Docs

Search the TenantsDB documentation.

READ search_docs

Searches the TenantsDB docs live from docs.tenantsdb.com. Useful for answering questions about TenantsDB itself, not about your data.

Input

Field	Type		Description
query	string	required	Keywords to search the docs for.
limit	integer	optional	Max results (default 3).

This tool has the OpenWorldHint annotation since it fetches data from the web.

←

→

→