AI Agent Quick Start¶

Connect an AI coding agent (Claude Code, Cursor, Copilot, Windsurf, etc.) to your Centrali workspace. First, create an account or accept a workspace invitation and confirm your console user has access to the intended workspace.

1. Connect with Hosted OAuth¶

Most interactive AI clients should use the hosted MCP server. Service-account auth is still useful for headless automation and CI.

Recommended: Hosted MCP Server¶

Add the hosted MCP URL to your client:

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

On first connection, your client opens a browser for login and workspace selection. Sign in with your Centrali account and select the workspace you want to use.

You do not need to create a service account, copy a client secret, or set environment variables for this path. Tool calls use your signed-in user identity and its workspace permissions; a service account's groups do not affect hosted OAuth access. Once connected, continue to capability discovery below.

For CI or headless automation, see Optional: Stdio Package With a Service Account.

2. Discover Capabilities¶

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

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

3. 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', {
    page: { limit: 10 }
  });
  return { success: true, data: records };
}

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

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

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

6. 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 { CentraliSDK } from '@centrali-io/centrali-sdk';

const centrali = new CentraliSDK({
  clientId: process.env.CENTRALI_CLIENT_ID,
  clientSecret: process.env.CENTRALI_CLIENT_SECRET,
  baseUrl: 'https://centrali.io',
  workspaceId: 'my-workspace', // current SDK option name; pass the workspace slug
});

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

import { CentraliSDK } from '@centrali-io/centrali-sdk';

const centrali = new CentraliSDK({
  publishableKey: 'pk_live_...',
  baseUrl: 'https://centrali.io',
  workspaceId: 'my-workspace', // current SDK option name; pass the workspace slug
});

7. Debug Issues¶

When something goes wrong:

1. Hosted OAuth connection or permission errors: Complete browser sign-in and confirm the selected workspace. If authentication expires, reconnect through your client's sign-in flow. For 403 Forbidden, check your signed-in user's access to the requested resource — creating a service account does not fix hosted OAuth access.
2. Stdio permission errors (403): Check the configured service account's workspace and group permissions — see Service Accounts
3. Compute failures: Inspect function runs — get_function_run(runId) shows status, output, and errors
4. Orchestration failures: Use get_orchestration_run(runId, includeSteps=true) to see step-by-step execution details
5. Common mistakes: See the AI Agent Troubleshooting Guide

Optional: Stdio Package With a Service Account¶

Use this separate connection path for CI or headless automation when browser login is not available. Hosted OAuth users can skip this section.

Create a Service Account¶

You need a service account only for the stdio path.

1. Select the intended workspace. Ask a workspace administrator to open Access → Service Accounts and create a service account, or use one already provisioned for this automation.
2. Save the Client ID (sa_... for newly created accounts) and Client Secret (sk_...) securely. The secret is shown only once. Existing legacy client IDs remain valid; use the exact ID issued to your account.
3. Open the service account's Groups tab and add it to workspace_developers for development, or a custom group with the specific permissions the automation needs. An administrator must configure group membership. Do not grant workspace_administrators by default.
4. Follow Account Setup to verify the service account's access with a fresh token. A successful token request alone does not prove resource access.

Without permission for a requested operation, the tool returns 403 Forbidden.

Connect via Stdio¶

For headless automation, add the stdio package to your MCP client configuration:

{
  "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": "<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.

Feature Availability¶

Not all features are available through all interfaces:

MCP file uploads¶

Hosted and stdio MCP both provide upload_file for standalone Storage uploads. The MCP client must supply the exact file bytes as canonical padded base64 or UTF-8 text; the tool cannot read a hidden chat attachment, local path, or source URL. Each file is limited to 256 KiB decoded, with a 768 KiB serialized content limit. Uploads are private by default; public uploads are restricted to supported passive MIME types. The tool returns a renderId and render/download URLs. To attach the uploaded file to a record, make a separate record update with that ID. Use the SDK or HTTP Storage upload path for larger files. See the MCP Server guide for input details and the public MIME allowlist.

Related Documentation¶

• MCP Server Setup — Full MCP configuration and tool reference
• SDK Reference — Client SDK documentation
• AI Agent Troubleshooting — Common failure modes and fixes
• Policies & Permissions — IAM resource and action reference
• Writing Functions — Compute function code guide
• Orchestrations — Multi-step workflow guide