Skip to content

AI Agent Quick Start

Get an AI coding agent (Claude Code, Cursor, Copilot, Windsurf, etc.) productive on Centrali in under 15 minutes.

1. Create a Service Account

You need a service account for the AI agent to authenticate with Centrali.

  1. In the Console, go to Settings → Service Accounts and create a new service account
  2. Save the Client ID (ci_...) and Client Secret (sk_...) — the secret is shown only once
  3. Open the service account, go to the Groups tab, and add it to the workspace_administrators group

Without group membership, every API call returns 403 Forbidden.

2. Connect via MCP

The fastest path for AI agents is the MCP server. Add this to your MCP client configuration:

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

Set CENTRALI_URL to your root domain (e.g., https://centrali.io), not the API or auth subdomain. The SDK derives the correct hosts automatically.

3. Discover Capabilities

The MCP server exposes describe_* tools that explain every Centrali concept. Start here:

Tool What it explains
describe_centrali Platform overview, feature matrix (SDK vs MCP vs Console), SDK integration examples
describe_collections Data schemas, field types, CRUD operations
describe_compute Function runtime, trigger types, input contract, async execution model
describe_orchestrations Multi-step workflows, encrypted params for secrets, step types
describe_pages Hosted pages, blocks, actions, variable binding
describe_search Full-text search, indexing, query syntax
describe_realtime Real-time subscriptions (SDK-only, not available via MCP)

An AI agent should call describe_centrali first to understand the platform, then drill into specific domains as needed.

4. Understand the Compute Contract

Compute functions run in a sandboxed Deno runtime. The function signature is always:

async function run() {
  // triggerParams — static config from the trigger definition
  // executionParams — dynamic data from the invocation
  // api — SDK client for Centrali APIs

  const records = await api.queryRecords('my-collection', { limit: 10 });
  return { success: true, data: records };
}

What triggerParams and executionParams contain depends on how the function was invoked:

Trigger type triggerParams executionParams
HTTP trigger Static params from trigger config { payload } — parsed request body
Endpoint trigger Static params from trigger config { payload, method, headers, query } — full HTTP context
Scheduled trigger Static params from trigger config {} — empty
Pages action { input, token } — from page action {} — empty
Orchestration step Orchestration input + previous outputs + decrypted encrypted params Not used (input arrives via triggerParams)

5. Handle Secrets

There is no secrets field on compute functions. The platform-native secret path is orchestration encrypted params:

  1. Create an orchestration with a compute step
  2. Set encryptedParams on the step — stored encrypted with AES-256-GCM at rest
  3. At execution time, encrypted params are decrypted and injected into triggerParams

For standalone triggers without orchestrations, secrets must be passed in the trigger payload. This is a known limitation.

6. Understand Async Execution

Compute execution is async by design. invoke_trigger returns a job ID, not the result.

invoke_trigger → job ID → poll get_function_run(runId) → status + result

Function run statuses: pending → running → completed | failure | timeout

For synchronous execution, use an endpoint trigger with invoke_endpoint instead.

7. Wire the SDK into an App

When building a web app (not just using MCP tools), install the SDK:

npm install @centrali-io/centrali-sdk

Next.js (server components / API routes):

import Centrali from '@centrali-io/centrali-sdk';

const centrali = new Centrali({
  clientId: process.env.CENTRALI_CLIENT_ID,
  clientSecret: process.env.CENTRALI_CLIENT_SECRET,
  baseUrl: 'https://dev.centrali.io',
  workspace: 'my-workspace',
});

React + Vite (client-side with publishable key):

import Centrali from '@centrali-io/centrali-sdk';

const centrali = new Centrali({
  publishableKey: 'pk_live_...',
  baseUrl: 'https://dev.centrali.io',
  workspace: 'my-workspace',
});
Context Auth method
Browser app Publishable key
Server app / API route Service account (client credentials)
MCP agent Service account (env vars)
Local dev Service account with workspace membership

8. Debug Issues

When something goes wrong:

  1. Permission errors (403): Check service account group membership — see Service Accounts
  2. Compute failures: Inspect function runs — get_function_run(runId) shows status, output, and errors
  3. Orchestration failures: Use get_orchestration_run(runId, includeSteps=true) to see step-by-step execution details
  4. Common mistakes: See the AI Agent Troubleshooting Guide

Feature Availability

Not all features are available through all interfaces:

Capability SDK MCP Console
Collections CRUD Yes Yes Yes
Records CRUD Yes Yes Yes
Compute functions Yes Yes Yes
Triggers Yes Yes Yes
Smart queries Yes Yes Yes
Orchestrations Yes Yes Yes
Pages Partial Yes Yes
Realtime subscriptions Yes No N/A
File uploads Yes No Yes
IAM management No Yes Yes