Tenant Routing

For SaaS apps, you can route MCP tool calls to AI SDK Project databases by passing tenant_id in tool arguments.

How Routing Works

1. Use your API key as usual (Authorization: Bearer mem_...).
2. Configure per-tenant database mappings with /api/sdk/v1/management/tenant-overrides.
3. Include tenant_id in tool arguments (get_context, add_memory, etc.).
4. The server resolves (owner_scope_key, tenant_id) to the mapped Turso database. owner_scope_key is derived from the authenticated key's billing owner (for example org:<id> or user:<id>), so routing survives API key rotation.

If tenant_id is omitted, requests use the API key's default workspace database.

When tenant auto-provisioning is enabled on the server, unknown tenant_id values can be provisioned on first use (new Turso DB + schema + mapping) without a separate management call.

Scope mapping:

• tenant_id = AI SDK Project (security/database boundary)
• user_id = end-user scope
• project_id = optional repo context filter (not auth boundary)

Manage Tenant Mappings

List Tenants

GET /api/sdk/v1/management/tenant-overrides

Returns all AI SDK Project mappings for your active API key. Returns all AI SDK Project mappings for your owner scope.

Create or Update Tenant

POST /api/sdk/v1/management/tenant-overrides

Create or update an AI SDK Project mapping. Two modes are available:

Provision — mode: "provision"

• Creates a new Turso database
• Initializes schema
• Stores mapping as status: "ready"

Attach — mode: "attach"

• Validates existing Turso credentials (SELECT 1)
• Stores mapping as status: "ready"

Example (provision):

{
  "tenantId": "acme-prod",
  "mode": "provision",
  "metadata": {
    "environment": "production"
  }
}

Example (attach):

{
  "tenantId": "acme-eu",
  "mode": "attach",
  "tursoDbUrl": "libsql://acme-eu.turso.io",
  "tursoDbToken": "<token>",
  "tursoDbName": "acme-eu"
}

Delete Tenant

DELETE /api/sdk/v1/management/tenant-overrides?tenantId=...

Soft-disables an AI SDK Project mapping (status: "disabled").

Using tenant_id in MCP Tools

Example JSON-RPC call:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "get_context",
    "arguments": {
      "tenant_id": "acme-prod",
      "project_id": "github.com/acme/platform",
      "query": "auth patterns"
    }
  }
}

Key Rotation Behavior

AI SDK Project mappings are owner-scoped, so key rotation does not require tenant-mapping copy or cleanup workflows. Routing remains stable as long as the key resolves to the same owner scope.

Error Codes

Tenant routing returns typed JSON-RPC errors:

• TENANT_ID_INVALID (-32602): tenant_id is not a non-empty string
• TENANT_DATABASE_NOT_CONFIGURED (-32004): no mapping exists for (owner_scope_key, tenant_id)
• TENANT_DATABASE_NOT_READY (-32009): mapping exists but status is not ready