MCP Server for AI Agents¶

The Centrali MCP (Model Context Protocol) server lets AI assistants like Claude, Cursor, Windsurf, and other MCP-compatible clients interact with your Centrali workspace. It exposes your collections, records, compute functions, orchestrations, pages, and IAM configuration as callable tools — so an AI agent can query data, create records, invoke functions, build pages, and manage access without writing any integration code.

Built on the @centrali-io/centrali-sdk and the Model Context Protocol standard.

Installation¶

No installation required. Run it directly with npx:

npx @centrali-io/centrali-mcp

Or install globally:

npm install -g @centrali-io/centrali-mcp

The MCP server communicates over stdio — your MCP client (Claude Desktop, Cursor, etc.) launches the process and talks to it over stdin/stdout.

Setup¶

Add Centrali to your MCP client configuration. The exact file depends on the client:

{
  "mcpServers": {
    "centrali": {
      "command": "npx",
      "args": ["@centrali-io/centrali-mcp"],
      "env": {
        "CENTRALI_URL": "https://centrali.io",
        "CENTRALI_CLIENT_ID": "<your-client-id>",
        "CENTRALI_CLIENT_SECRET": "<your-client-secret>",
        "CENTRALI_WORKSPACE": "my-workspace"
      }
    }
  }
}

{
  "mcpServers": {
    "centrali": {
      "command": "npx",
      "args": ["@centrali-io/centrali-mcp"],
      "env": {
        "CENTRALI_URL": "https://centrali.io",
        "CENTRALI_CLIENT_ID": "<your-client-id>",
        "CENTRALI_CLIENT_SECRET": "<your-client-secret>",
        "CENTRALI_WORKSPACE": "my-workspace"
      }
    }
  }
}

claude mcp add centrali \
  -e CENTRALI_URL=https://centrali.io \
  -e CENTRALI_CLIENT_ID=<your-client-id> \
  -e CENTRALI_CLIENT_SECRET=<your-client-secret> \
  -e CENTRALI_WORKSPACE=my-workspace \
  -- npx @centrali-io/centrali-mcp

Environment Variables¶

Authentication¶

The MCP server authenticates using service account client credentials. You need to create a service account before using the MCP server.

1. In the Centrali Console, go to Developers > Service Accounts
2. Click Create Service Account
3. Copy the client_id and client_secret
4. Assign appropriate roles/groups for the permissions your agent needs

See the Service Accounts guide for detailed instructions.

Getting Started¶

Once connected, instruct your AI agent to call describe_centrali first. This returns a full capability map with all available tools grouped by domain. From there, the agent can call domain-specific describe_* tools for detailed schema references before taking action.

A typical agent workflow looks like:

1. Discover — call describe_centrali to see what is available
2. Explore — call list_collections or describe_records to understand the data model
3. Act — create records, invoke triggers, build pages, etc.

Available Tools¶

The MCP server exposes 100+ tools across these domains:

Discovery¶

Call these first to understand the workspace schema and API shapes.

Collections¶

Records¶

Search¶

Compute¶

Smart Queries¶

Orchestrations¶

AI Features¶

Pages¶

Service Accounts and IAM¶

Publishable Keys¶

Identity¶

Resources¶

The MCP server also exposes MCP resources that clients can read:

MCP vs SDK vs Console¶

The MCP server wraps the SDK, so any operation available via MCP is also available programmatically through the SDK. The MCP server adds discovery tools (describe_*) and IAM management that the SDK does not expose directly.

Common Failure Modes¶

When an AI agent is not getting expected results, check these common issues:

Wrong host in CENTRALI_URL¶

Set CENTRALI_URL to your root domain (e.g., https://centrali.io or https://dev.centrali.io). The SDK automatically derives the API host (api.centrali.io) and auth host (auth.centrali.io) from this value. Do not pass https://api.centrali.io or https://auth.centrali.io directly.

Workspace slug mismatch¶

The CENTRALI_WORKSPACE value must be the workspace slug (e.g., acme-corp), not the display name or UUID. You can find it in the Console URL: https://console.centrali.io/acme-corp/....

Insufficient permissions¶

If an operation returns a 403, the service account does not have the required permission. Use the IAM tools to diagnose:

1. Call scan_service_account_permissions to see the full access matrix
2. Call simulate_service_account_permission for the specific resource + action
3. Call generate_remediation to get fix options
4. Call apply_remediation to grant the missing access

Plan-gated features¶

Some features (AI insights, anomaly detection, advanced orchestration options) are only available on certain workspace plans. If a tool returns a plan-related error, the workspace needs to be upgraded. The error message will indicate which plan is required.

Async compute execution¶

invoke_trigger returns a job ID, not the result. The agent must poll get_compute_job_status or get_function_run until the job completes. For synchronous execution, use invoke_endpoint with an HTTP trigger instead.

Rate limits¶

Service accounts are subject to API rate limits. If the agent is making many rapid requests, it may hit 429 Too Many Requests. Back off and retry.

Local Development¶

For local development with Centrali services running on your machine, configure the MCP server to point at your local Traefik gateway:

{
  "mcpServers": {
    "centrali-local": {
      "command": "npx",
      "args": ["@centrali-io/centrali-mcp"],
      "env": {
        "CENTRALI_URL": "http://centrali.localhost",
        "CENTRALI_CLIENT_ID": "<local-sa-client-id>",
        "CENTRALI_CLIENT_SECRET": "<local-sa-client-secret>",
        "CENTRALI_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Local routing (via Traefik):

See the local development guide for setting up the full stack.

Testing with the MCP Inspector¶

The MCP Inspector is a visual debugging tool for MCP servers. Use it to test tools interactively:

CENTRALI_URL=https://dev.centrali.io \
CENTRALI_CLIENT_ID=your-client-id \
CENTRALI_CLIENT_SECRET=your-client-secret \
CENTRALI_WORKSPACE=your-workspace \
npx @modelcontextprotocol/inspector node node_modules/@centrali-io/centrali-mcp/dist/index.js

This opens a browser UI where you can call any tool, inspect responses, and debug issues before connecting a real AI agent.