MCP — Getting Started with Praxsuite DataEngine

The Praxsuite MCP server lets any AI assistant that supports the Model Context Protocol (Claude, Cursor, Claude Code, etc.) read and write your workspace data directly — no custom API code, no endpoint configuration.

Under the hood it is the same DataEngine and the same permission system as the rest of the API Gateway. Every table scope, column restriction, and row-level filter you have configured applies equally to MCP tool calls.

How It Works

The MCP server is reachable at:

https://gateway.praxsuite.com/{workspaceId}/mcp

It speaks JSON-RPC 2.0 over Streamable HTTP (the current MCP standard). The AI client POSTs requests to this URL and receives JSON responses. You authenticate with the same sk_live_ API key you already use for PraxQL queries.

                Claude / Claude Code / Cursor
                        │
                        │  POST (JSON-RPC 2.0)
                        │  Authorization: Bearer sk_live_xxx
                        ▼
          gateway.praxsuite.com/{workspaceId}/mcp
                        │
                        │  same auth + scope enforcement
                        ▼
              Praxsuite DataEngine (PraxQL)
                        │
                        ▼
                   PostgreSQL

The AI never has direct database access. It calls tools, the tools run through your Gateway permissions, and only data the key is allowed to see is returned.

Prerequisites

Before connecting an AI client you need:

1. A workspace in Praxsuite with at least one DataEngine table.

2. A Server API Key (sk_live_) with table scopes configured for the data you want to expose. See API Keys for how to create one.

3. Your Workspace ID — find it in the workspace URL or in Settings → General. It is a UUID like 3fa85f64-5717-4562-b3fc-2c963f66afa6.

Only use sk_live_ keys (Server Keys) for MCP. Never use a pk_live_ (Public Key) — those are for browser clients and have weaker security guarantees.

Step 1 — Create an API Key

Go to API Gateway → API Keys in your workspace and click Create.

After clicking Create, copy the full key — it starts with sk_live_ and is shown only once.

Step 2 — Connect Your AI Client

Claude Desktop

Add the following to your claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "praxsuite": {
      "type": "http",
      "url": "https://gateway.praxsuite.com/{workspaceId}/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

Replace {workspaceId} with your actual workspace UUID and sk_live_your_key_here with the key you created in Step 1.

Claude Code (CLI)

claude mcp add praxsuite \
  --transport http \
  --url "https://gateway.praxsuite.com/{workspaceId}/mcp" \
  --header "Authorization: Bearer sk_live_your_key_here"

Cursor

In Cursor, open Settings → MCP and add a new server:

{
  "praxsuite": {
    "url": "https://gateway.praxsuite.com/{workspaceId}/mcp",
    "headers": {
      "Authorization": "Bearer sk_live_your_key_here"
    }
  }
}

Step 3 — Verify the Connection

Once connected, ask the AI:

"List the tables available in my Praxsuite workspace"

It will call the list_tables tool and return the table names and GUIDs your key has access to. If you see them, you're connected.

Available Tools

The MCP server exposes these tools. The AI chooses which ones to call based on your instructions.

Schema Tools

ow Tools

Advanced Tool

File Too

Example Conversations

Reading data

You: Show me the last 10 orders from customers in Chile

Claude: (calls list_tables → finds "Orders" table)
        (calls describe_table → sees Status, Country, CreatedAt columns)
        (calls get_rows with filters: Country=Chile, sort: CreatedAt desc, limit: 10)
        Here are the 10 most recent orders from Chile: ...

Writing data

You: Mark order ID abc-123 as "Shipped"

Claude: (calls update_row with table_id, row_id=abc-123, values={Status:"Shipped"})
        Done. Order abc-123 has been updated to Shipped.

Aggregations

You: How many active clients do I have per country?

Claude: (calls aggregate_rows: fn=count, field=Id, group_by=Country, filters: Status=Active)
        Active clients by country:
          Chile — 142
          Argentina — 87
          Mexico — 63

Permissions & Security

The MCP server enforces the exact same rules as regular API Gateway calls:

• The key only sees tables in its Table Scopes. Tables without a scope are invisible.

• Columns marked as restricted in Column Scopes are never returned, even if the AI asks.

• Masking rules apply — masked columns return the masked value regardless of the tool used.

• The AllowSchemaIntrospection flag on each table scope controls whether describe_table works for that table. If disabled, the AI cannot inspect the column structure.

• Write operations (insert_row, update_row, delete_row) require the key to have write or readwrite access on that table.

Recommendation: create a separate, dedicated API key for each AI integration with the minimum scopes required. Do not reuse a key that also powers your production backend.

Troubleshooting

The AI says it can't find my tables

Check that:

1. The key has Table Scopes configured — a key with no scopes sees nothing.

2. AllowSchemaIntrospection is enabled on the table scope (controls describe_table).

3. The Workspace ID in the URL is correct.

Authentication errors (401)

• Verify the key starts with sk_live_ — public keys (pk_live_) are not accepted by the MCP endpoint.

• Confirm the key is Active and not expired or revoked in API Keys tab.

• Check that the Authorization: Bearer header is being sent (some clients use x-api-key — both are accepted).

The AI can list tables but not read/write rows

The key has AllowSchemaIntrospection but may be missing the actual read/write access level on the table scope. Go to API Keys → Edit and update the access level.

Mutations are being rejected

Confirm the table scope access level is write or readwrite, not read.

What Praxsuite Never Does

• Never exposes your raw database structure. Physical table and column names (USERTABLE_, COL_) are never sent to the AI client.

• Never bypasses your Gateway rules. There is no admin or debug mode. MCP is the same data path as every other API call.

• Never logs your AI conversation. Query Logs record the tool calls (table accessed, operation type) the same way a regular API call is logged — not the conversational context from the AI client.