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.

Two ways to connect¶

Option 1: Hosted MCP Server (recommended)¶

The easiest way to connect. Add a single URL — authentication happens in the browser.

{
  "mcpServers": {
    "centrali": {
      "type": "url",
      "url": "https://mcp.centrali.io"
    }
  }
}

claude mcp add centrali --transport http https://mcp.centrali.io

{
  "mcpServers": {
    "centrali": {
      "type": "url",
      "url": "https://mcp.centrali.io"
    }
  }
}

How it works¶

1. Add the URL — paste the configuration snippet into your AI client
2. Authenticate — your client opens a browser window for you to log in with your Centrali account
3. Select workspace — choose which workspace the agent operates in (auto-selected if you only have one)
4. Start using — ask the agent to call describe_centrali and explore from there

No API keys, client IDs, or environment variables required. The token carries your user identity, so audit logs show you performed the action.

Option 2: Stdio with Service Account (CI/automation)¶

For headless environments where browser login isn't possible. Uses service account credentials with RBAC permissions.

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

Or run directly with npx:

npx @centrali-io/centrali-mcp

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

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

Environment Variables (stdio mode)¶

Service Account Setup¶

A freshly created service account has no permissions by default. You must assign it a role before the MCP server can do anything useful, otherwise every tool call will return 403 Forbidden.

Quickest setup — full admin access:

1. In the Console, go to Settings > Service Accounts
2. Create a service account and save the credentials
3. Open the service account, go to the Groups tab
4. Add it to the workspace_administrators group

Least-privilege setup: Create a custom group with a policy scoped to the specific resources the MCP agent needs. See Policies and Permissions for details.

Migrating from OAuth stdio to hosted¶

If you were previously using CENTRALI_OAUTH_CLIENT_ID or CENTRALI_OAUTH_CLIENT_SECRET with the stdio package, those auth modes have moved to the hosted MCP server.

Step-by-step migration¶

1. Remove the old configuration — delete the command, args, and env block from your MCP client config
2. Add the hosted URL — replace with { "type": "url", "url": "https://mcp.centrali.io" }
3. Restart your AI client — on next connection, authenticate in the browser
4. Delete the old OAuth app (optional) — the OAuth app in Settings > OAuth Apps is no longer needed for this use case

Before and after¶

Before (stdio + OAuth):

{
  "mcpServers": {
    "centrali": {
      "command": "npx",
      "args": ["@centrali-io/centrali-mcp"],
      "env": {
        "CENTRALI_URL": "https://centrali.io",
        "CENTRALI_OAUTH_CLIENT_ID": "oc_your_client_id",
        "CENTRALI_OAUTH_CLIENT_SECRET": "os_your_client_secret",
        "CENTRALI_WORKSPACE": "my-workspace"
      }
    }
  }
}

After (hosted):

{
  "mcpServers": {
    "centrali": {
      "type": "url",
      "url": "https://mcp.centrali.io"
    }
  }
}

FAQ¶

Q: What about my existing service account configuration? A: Service accounts still work with the stdio package. No migration needed — only browser OAuth users need to switch.

Q: Will the old OAuth env vars cause errors? A: The stdio package will detect CENTRALI_OAUTH_CLIENT_ID and print a migration message with instructions. It will not start the MCP server.

Q: Can I use the hosted server for CI/automation? A: The hosted server requires browser-based login, so it's not suitable for headless environments. Use the stdio package with a service account for CI/automation.

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.

This only applies to stdio mode. The hosted MCP server handles routing automatically.

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

This only applies to stdio mode. The hosted MCP server shows a workspace picker during authentication.

Insufficient permissions¶

A freshly created service account has no permissions by default. If every tool call returns 403 Forbidden, the service account has not been assigned a role.

Fix — assign a role in the Console:

1. Open the service account in Settings > Service Accounts
2. Go to the Groups tab and add it to the workspace_administrators group (or a custom group with the permissions you need)
3. Retry the MCP tool call

For least-privilege setups, create a custom group with a policy scoped to the specific resources the MCP agent needs. See Policies and Permissions for details.

Diagnosing specific permission issues:

If the service account has a role but a specific operation fails, use the IAM tools built into the MCP server:

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