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, and IAM configuration as callable tools — so an AI agent can query data, create records, invoke functions, 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 service account, API keys, client IDs, or environment variables required. You can skip Option 2 and continue to Getting Started. The token carries your user identity, so audit logs show you performed the action.

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

This is an optional, separate connection path for headless environments where browser login isn't possible. It uses service account credentials with RBAC permissions; hosted OAuth users do not need this setup.

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 to a group with the required permissions before the MCP server can use protected resources, otherwise every tool call will return 403 Forbidden.

Development setup:

1. Select the intended workspace. Ask a workspace administrator to open Access → Service Accounts and create or select the service account.
2. Save its client ID and one-time secret securely. New client IDs use sa_; existing legacy IDs remain valid.
3. Open its Groups tab and add workspace_developers for development, or a custom group granting the specific actions the agent needs. Do not grant workspace_administrators by default.
4. Request a fresh token and verify a permitted resource call as described in Account Setup. A token alone does not prove authorization.

The workspace_developers group does not grant access to service-account or auth-provider management tools. Those tools require separate administrator permissions.

See Policies and Permissions for custom access rules.

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 Access → 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 and inspect workflows.

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¶

Compute¶

Smart Queries¶

Orchestrations¶

AI Features¶

Pages (retired)¶

Pages tools and describe_page_blocks were removed in CEN-1474. Use SDK or REST to connect an external application frontend.

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.

Upload files with MCP¶

Both the hosted MCP server and the stdio package expose upload_file for uploading a standalone file to the authenticated workspace's Storage. The tool requires files/create permission on the destination folder; an optional location selects an existing folder and defaults to /root/shared.

Provide the exact file bytes as canonical padded base64 (contentEncoding: "base64") or provide UTF-8 text (contentEncoding: "utf8"). The file is limited to 256 KiB decoded and the serialized content string to 768 KiB. Base64 is useful for binary data and heavily escaped text. The MCP client must be able to read and send the bytes: upload_file cannot read hidden chat attachments, local paths, or source URLs on the client's behalf.

Uploads are private by default. Set isPublic: true only when public access is intended; public uploads are limited to PNG, JPEG, GIF, WebP, plain text, JSON, MPEG/OGG/WAV audio, and MP4/WebM video. HTML, SVG, and other active document types must remain private. Private render and download URLs require normal authentication.

The response includes a renderId and render/download URLs. Uploading creates a standalone Storage file; attaching it to a record requires a separate record update using the renderId. Repeating an upload can create a duplicate. For files larger than 256 KiB, use the SDK or HTTP Storage upload path instead.

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.

Hosted OAuth: sign-in and permissions¶

Complete browser sign-in with your Centrali account and confirm the selected workspace. If the connection returns 401 Unauthorized or authentication has expired, reconnect through your client's sign-in flow.

For 403 Forbidden, check your signed-in user's access to the requested resource in that workspace. Hosted MCP uses your user identity; service-account group membership is not the fix for this connection mode. See Policies and Permissions.

Stdio service account: insufficient permissions¶

A freshly created service account has no permissions by default. If every tool call returns 403 Forbidden, the service account may lack the required group permissions.

Fix — assign a role in the Console:

1. Ask a workspace administrator to open Access → Service Accounts and check the account's Groups tab.
2. Add workspace_developers for development or a custom group with the required resource actions.
3. Obtain a fresh token and retry the MCP tool call. See Account Setup.

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 service-account permission issues (stdio only):

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.