MCP — Connect any AI client to your workspace

The Praxsuite MCP server lets an AI assistant that speaks the Model Context Protocol 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.

New to Praxsuite? You need an account and a workspace before any of this works. Start at Create your Praxsuite account and come back here.

How it works

One endpoint, the same for every client:

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 / VS Code
                        |
                        |  POST (JSON-RPC 2.0)
                        |  Authorization: Bearer sk_live_xxx
                        v
          gateway.praxsuite.com/{workspaceId}/mcp
                        |
                        |  same auth + scope enforcement
                        v
              Praxsuite DataEngine (PraxQL)
                        |
                        v
                  your workspace data

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.

Because the endpoint, the transport, the authentication and the tool catalogue are identical for every client, the only thing that changes from one AI to the next is where you paste the configuration. That is what the client sections below are for.

Which AI clients can connect

The Copilot that ships with Windows is not the same product as GitHub Copilot in VS Code, and it is not an MCP client. Microsoft's documented paths for connecting a custom MCP server are GitHub Copilot in VS Code, Copilot Studio (for agents makers build) and Microsoft 365 Copilot federated connectors (provisioned by an administrator). None of them is "type a server URL into the Copilot app on the taskbar". If Copilot on Windows is the only AI you have, you cannot follow this guide — install VS Code and use GitHub Copilot there instead.

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. Create one in API Gateway → API Keys.

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. A pk_live_ (Public Key) is for browser clients and is rejected by the MCP endpoint.

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.

Two defaults worth knowing before you go hunting for a bug:

• A new key is created with the Data tool group at readwrite and every other group (schema, apps, users, credentials, security) at None. So reading and writing rows works immediately; tools that create tables, deploy apps or manage users are absent from tools/list until an administrator grants them. See API Gateway → Credentials → MCP Tool Permissions.

• AllowSchemaIntrospection is off by default on each table scope. It controls describe_table. Turn it on for the tables the AI needs to understand.

Step 2 — Connect your AI client

Replace {workspaceId} with your workspace UUID and sk_live_your_key_here with the key from Step 1 in every snippet below.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• 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"
      }
    }
  }
}

Restart Claude Desktop afterwards.

Claude Code (CLI)

The URL is a positional argument, not a flag:

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

Add --scope user to make the server available in every project instead of only the current one.

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"
    }
  }
}

VS Code + GitHub Copilot

There are two routes. The extension is the shorter one.

Route A — the Praxsuite extension (recommended)

Install Praxsuite (publisher Praxsuite, extension ID Praxsuite.praxsuite) from the VS Code Marketplace, or from Open VSX if your editor uses that registry. It needs VS Code 1.99 or newer.

Then open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Praxsuite: Configure Workspace. It asks for three things in order:

1. your Workspace ID,

2. the Gateway URL (https://gateway.praxsuite.com),

3. your sk_live_ key — stored in VS Code's encrypted secret storage, never written into a settings file.

The extension then does two things at once:

• It writes `.vscode/mcp.json` for you with the server, URL and Authorization header already filled in, so Copilot agent mode gets the full MCP tool catalogue. Reload the window when it offers to.

• It registers a set of Copilot language-model tools (praxsuite_list_tables, praxsuite_get_rows, praxsuite_execute_praxql, the file and app tools, and more). These show up in Copilot Chat without any MCP involvement at all.

It also adds a Praxsuite view to the activity bar where you can browse tables and run PraxQL directly.

The extension does not have its own login. It asks for the same sk_live_ key as every other client — it just saves you from hand-editing JSON and keeps the key out of your repository.

Route B — write .vscode/mcp.json by hand

Create .vscode/mcp.json in your project. Use an input rather than pasting the key into the file, so it never reaches source control:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "praxsuite-key",
      "description": "Praxsuite sk_live_ API key",
      "password": true
    }
  ],
  "servers": {
    "praxsuite": {
      "type": "http",
      "url": "https://gateway.praxsuite.com/{workspaceId}/mcp",
      "headers": {
        "Authorization": "Bearer ${input:praxsuite-key}"
      }
    }
  }
}

VS Code prompts for the key the first time the server starts and stores it separately from the file.

To make the server available in every project instead of one, run MCP: Open User Configuration from the Command Palette and put the same servers block there. MCP: Add Server walks you through the same thing with a guided flow.

Then open Copilot Chat, switch it to Agent mode, and the Praxsuite tools appear in the tool picker.

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 are connected.

Authentication: API key only, for now

Every client above authenticates with an sk_live_ key in an Authorization: Bearer header. There is no browser sign-in flow where the AI asks you for permission and connects itself.

The Gateway does publish OAuth discovery documents — a Protected Resource Metadata document at /.well-known/oauth-protected-resource, authorization-server metadata, and an OpenAPI description — and the MCP endpoint does accept registered AI connectors, which is the path used for a Claude.ai custom connector, set up from API Gateway → Credentials → AI Connectors. But there is no registration_endpoint, so an arbitrary MCP client cannot register itself and connect on its own. Paste the key.

Available tools

The MCP server exposes these tools. The AI chooses which ones to call based on your instructions. What a given key actually sees is narrowed by its MCP tool permissions, so a tool it may not use is absent from tools/list rather than present and failing.

Schema tools

Row tools

Advanced tool

File tools

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 and 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. It is off by default, so a brand-new scope has to have it switched on before the AI can inspect the column structure.

• Write operations (insert_row, update_row, delete_row) require the key to have write or readwrite access on that table. A new table scope is created as read.

• Beyond table scopes, MCP tool permissions decide which tool groups the key may call at all. A new key gets Data and nothing else.

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 (it controls describe_table, and it is off by default).

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 the API Keys tab.

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

• If the message says the key is not enabled for MCP, an administrator has turned that switch off on the key itself. It is on by default for new keys.

A tool I expected is missing

tools/list only returns what the credential may actually use. If the tool you want belongs to a group the key was not granted, it will not appear at all. Grant the group in API Gateway → Credentials → MCP Tool Permissions.

The AI can list tables but not read or 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.

Copilot in VS Code doesn't show the tools

• Copilot Chat must be in Agent mode; MCP tools are not offered in ask mode.

• Reload the window after .vscode/mcp.json changes.

• Check the MCP server's output panel for a connection error — a bad key shows up there as a 401, not as a missing tool.

What Praxsuite never does

• Never exposes how your data is physically stored. The AI client sees only the logical table and column names you configured; the storage layer is not addressable from a tool call.

• 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.