AI Integration (MCP)

SchemaStack supports the Model Context Protocol (MCP) — an open standard that lets AI assistants like Claude interact directly with your workspace data. Instead of copy-pasting data or writing API calls, your AI assistant can browse schemas, query data, and even create records through a natural conversation.

What Can AI Do With Your Workspace?

Once connected, an AI assistant can:

• Browse your schema — list workspaces, views (tables), and columns
• Query data — search and retrieve records with pagination
• Create and edit records — insert new rows or update existing values
• Manage schema — create views, add columns, set up validation constraints
• Understand your data model — read form schemas to understand column types and constraints

Access Levels

Each workspace has its own MCP access level, giving you fine-grained control over what AI clients can do:

Level	Read Schema	Query Data	Create/Edit Records	Modify Schema
Disabled (default)	No	No	No	No
Read-Only	Yes	Yes	No	No
Data-Only	Yes	Yes	Yes	No
Full	Yes	Yes	Yes	Yes

TIP

Start with Read-Only to let AI assistants explore and query your data safely. Upgrade to Data-Only or Full when you need AI-assisted data entry or schema management.

Setting Up MCP Access

1. Enable MCP for Your Workspace

In the Admin app, navigate to your workspace settings and set the MCP access level:

PUT /api/workspaces/{workspaceUuid}/mcp-config
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "accessMode": "READ_ONLY"
}

Only workspace administrators (OWNER or ADMIN role) can change MCP settings.

2. Connect Claude Desktop

Add SchemaStack as an MCP server in your Claude Desktop configuration file:

macOS (~/.claude/claude_desktop_config.json)

{
  "mcpServers": {
    "schemastack": {
      "url": "https://your-schemastack-instance.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

Windows (%APPDATA%/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "schemastack": {
      "url": "https://your-schemastack-instance.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

3. Connect Claude Code

Add SchemaStack as an MCP server in your project's .mcp.json file:

{
  "mcpServers": {
    "schemastack": {
      "type": "url",
      "url": "https://your-schemastack-instance.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

4. Start Using It

Once connected, you can ask your AI assistant things like:

• "What workspaces do I have?"
• "Show me the columns in the Customers view"
• "Query the first 10 orders"
• "Add a new column called 'priority' to the Tasks view"
• "Create a new customer record with name 'Acme Corp' and email '[email protected]'"

Available Tools

Your AI assistant has access to 18 tools organized by category:

Workspace Tools

Tool	Description
get_workspace	Get workspace details including its views

View Tools

Tool	Description
list_views	List all views (tables) in a workspace
get_view	Get view details with column definitions
create_view	Create a new view (database table)
update_view	Update a view's name or slug
delete_view	Delete a view and its data

Column Tools

Tool	Description
list_columns	List all columns in a view
add_column	Add a new column with a display name and widget type (STRING, EMAIL, NUMBER, etc.)
update_column	Update column display name, widget type, or settings
delete_column	Remove a column

Data Tools

Tool	Description
get_form_schema	Get the full schema for a view (types, constraints, widgets)
query_data	Query records with pagination
get_record	Get a single record by ID
create_record	Create a new data record
update_record	Update a cell value in a record

Constraint Tools

Tool	Description
list_constraints	List validation constraints on a column
add_constraint	Add a validation constraint (NOT_BLANK, MAX_LENGTH, EMAIL, etc.)
delete_constraint	Remove a validation constraint

Transport Protocol

SchemaStack uses the Streamable HTTP MCP transport (not SSE). This is the newer, stateless-friendly transport from the MCP specification (2025-03-26).

How It Works

All communication happens via POST requests to a single /mcp endpoint. The server uses sessions to track state:

1. Initialize — your first request must be an initialize call. The server returns an Mcp-Session-Id header in the response.
2. Include the session ID — all subsequent requests must include the Mcp-Session-Id header from step 1.

Most MCP clients (Claude Desktop, Claude Code, Cursor) handle this handshake automatically. If you're building a custom integration, here's the flow:

# Step 1: Initialize and capture the session ID
curl -D- -X POST https://your-instance.com/mcp \
  -H "Authorization: Bearer <your-mcp-api-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-app", "version": "1.0"}
    }
  }'
# → Response includes: Mcp-Session-Id: abc123...

# Step 2: Call tools with the session ID
curl -X POST https://your-instance.com/mcp \
  -H "Authorization: Bearer <your-mcp-api-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: abc123..." \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
       "params": {"name": "get_workspace", "arguments": {}}}'

TIP

If you see the error Mcp-Session-Id header not found, your client is skipping the initialize handshake. Make sure it sends an initialize request first and includes the returned session ID on all follow-up requests.

Schema Migrations

When an admin changes a column's type or adds constraints, a schema migration runs on the database. During this time, the affected table may be temporarily unavailable.

If your AI assistant tries to read or write data on a table that's being migrated, it will receive an error like:

Table 'customers' is currently being migrated (operation: abc-123, impact: BLOCKING). Please retry in ~15 seconds.

The AI assistant can inform you and retry after the migration completes. Most migrations take seconds — only large tables with type changes take longer.

What's blocked depends on the migration type:

Migration	Reads blocked?	Writes blocked?
Column type change (PostgreSQL)	Yes	Yes
Column type change (MySQL)	No	Yes
Add NOT NULL (PostgreSQL)	Yes	Yes
Add NOT NULL (MySQL)	No	No
Add unique constraint	No	Yes

TIP

If your AI workflow needs uninterrupted access, coordinate schema changes with your team to avoid running migrations during active AI sessions.

Security

MCP access uses the same authentication and authorization as the REST API:

• Authentication: JWT Bearer token — the same token you use for the REST API
• Authorization: Your existing RBAC roles (Owner, Admin, Member, Viewer) still apply. MCP access levels are an additional gate on top of role-based permissions.
• Organisation isolation: AI assistants can only access workspaces within the organisation your token is scoped to

WARNING

Your JWT token grants the AI assistant the same permissions you have. Only share tokens with AI clients you trust, and use the most restrictive MCP access level that meets your needs.

Checking MCP Status

To check the current MCP configuration for a workspace:

GET /api/workspaces/{workspaceUuid}/mcp-config
Authorization: Bearer <your-token>

Response:

{
  "accessMode": "READ_ONLY"
}