Webhooks
Send signed CentraKit events to your HTTPS endpoints and receive external webhooks that start workflows, including signatures, secret and token rotation, delivery retries, and the REST and MCP operations.
CLI
Every centrakit CLI command and global flag, how it signs in and resolves the API base URL, its configuration files and environment variables, and how releases are packaged.
Webhooks
Send signed CentraKit events to your HTTPS endpoints and receive external webhooks that start workflows, including signatures, secret and token rotation, delivery retries, and the REST and MCP operations.
CLI
Every centrakit CLI command and global flag, how it signs in and resolves the API base URL, its configuration files and environment variables, and how releases are packaged.
Connect AI clients to the CentraKit product MCP server and the docs MCP server, with OAuth setup, scopes, approvals and the full list of 74 product tools.
CentraKit runs two MCP servers:
https://api.centrakit.com/api/mcp acts on your organization data with your permissions. It needs OAuth.https://docs.centrakit.com/mcp reads these docs. It is public and read-only.| Server | Cursor | VS Code | Claude Code |
|---|---|---|---|
| Product API | Add to Cursor | Add to VS Code | claude mcp add --transport http centrakit https://api.centrakit.com/api/mcp |
| Docs | Add to Cursor | Add to VS Code | claude mcp add --transport http centrakit-docs https://docs.centrakit.com/mcp |
The product server starts an OAuth sign-in on first use. The docs server needs no authentication.
The docs server at https://docs.centrakit.com/mcp (locally https://docs.localhost/mcp) is built on fumadocs-core/mcp and has three read-only tools:
| Tool | Input | Returns |
|---|---|---|
list_pages | none | The page index, the same content as /llms.txt. |
search | query, optional locale | Matching docs sections with their page URLs. |
get_page | url, a page pathname such as /developers/mcp | The page as Markdown. |
A typical agent calls list_pages or search first, then get_page for the pages it needs. The same content is available without MCP; see Docs for AI agents.
The product server speaks the stateless MCP 2026-07-28 protocol over Streamable HTTP, and serves clients that use the 2025-era Streamable HTTP protocol through the same endpoint.
| Environment | Endpoint |
|---|---|
| Production | https://api.centrakit.com/api/mcp |
| Local | https://api.localhost/api/mcp |
The current protocol has no transport sessions and no Mcp-Session-Id. Legacy HTTP+SSE endpoints such as /api/sse and /api/message do not exist.
Clients can call server/discover for the supported protocol versions, server identity (centrakit-api) and capabilities. server/discover and tools/list responses carry a one-hour public cache hint because the catalog only changes with a deployment. Tool results are never cached.
Every request to the product server needs a bearer token.
401 with a WWW-Authenticate header that points to https://api.centrakit.com/.well-known/oauth-protected-resource.https://<project-ref>.supabase.co/auth/v1.The server verifies the token's issuer, signature, expiry and audience. Supabase OAuth tokens usually keep the default authenticated audience, and the server accepts it as well as the resource URL https://api.centrakit.com/api/mcp and any MCP_RESOURCE_AUDIENCE the deployment configures. See Authentication.
Each tool requires one OAuth scope, which must be present in the token's scope claim:
| Tool kind | Required scope |
|---|---|
| Read | mcp:read |
| Mutation | mcp:write |
Every mutation tool requires mcp:write; there are no exceptions. A call without the scope fails with OAuth scope mcp:write is required for this MCP tool. The scope only allows the call to start. The REST route then applies your organization permissions, so a token can never do more than its user.
For local agent work, centrakit login runs the same PKCE flow and stores a refreshable session. For CI and hosts that inject their own credentials, pass a bearer token directly (centrakit --token <access-token> or CENTRAKIT_TOKEN). See CLI.
Hosts that support Streamable HTTP and OAuth connect to the URL directly:
{
"mcpServers": {
"centrakit": {
"url": "https://api.centrakit.com/api/mcp"
}
}
}mcp-remoteHosts that only launch local commands can bridge through mcp-remote, which also handles the OAuth flow:
{
"mcpServers": {
"centrakit": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://api.centrakit.com/api/mcp"]
}
}
}| Client | Config file | Notes |
|---|---|---|
| Cursor | ~/.cursor/mcp.json | Direct URL. Fall back to mcp-remote if OAuth fails. |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | Use mcp-remote. |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | Direct URL or mcp-remote. |
Each tool maps to one REST operation and takes a nested input:
{
"pathParams": { "organizationId": "1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f" },
"query": { "limit": 50, "offset": 0, "q": "pump" },
"body": {}
}pathParams holds the path parameters, such as organizationId, taskId or quoteId. Organization-scoped tools always need the organization UUID. No tool lists organizations and getCurrentUser returns only the user's ID, email and sign-in dates, so get the ID from the user, from centrakit orgs list, or from GET /api/v1/organizations.query is optional and holds list filters and pagination.body holds the request body for mutations.Inputs are validated against the generated operation schemas before the call, and the REST route validates them again. The server then calls the matching REST operation with the same bearer token, so validation, permissions, audit logging and errors match the REST API.
Results include a text fallback and structuredContent when the API returns JSON. Each tool also publishes _meta entries com.centrakit/operation-kind (read or mutate) and com.centrakit/required-oauth-scope, plus annotations: readOnlyHint for reads, and destructiveHint, openWorldHint and idempotentHint for mutations, derived from the action catalog.
The catalog is a deliberate allowlist of 74 REST operations: 41 read tools and 33 mutation tools. Tool names are the OpenAPI operation IDs.
| Group | Read tools | Mutation tools |
|---|---|---|
| Account | getApiHealthV1, getCurrentUser | |
| Tasks | listTasks, getTask | createTask, updateTask, setTaskStatus |
| Customers and assets | listCustomers, getCustomer, listCustomerAssets, getCustomerAsset | createCustomer, updateCustomer |
| Products | listProducts, getProduct | createProduct, updateProduct |
| Quotes | listQuotes, getQuote | createQuote, updateQuote |
| Tags | listTags, getTag | createTag, updateTag |
| Orders | listOrders, getOrder | createOrder, confirmOrder, cancelOrder |
| Shipments | listShipments, getShipment | shipShipment |
| Purchase orders | listPurchaseOrders, getPurchaseOrder | createPurchaseOrder, receivePurchaseOrder |
| Inventory and promotions | listInventoryLevels, validatePromotion | |
| Agenda | listAgendaItems, getAgendaItem | createAgendaItem, updateAgendaItem, deleteAgendaItem, moveAgendaItem |
| Files | listFileDrives, listFileNodeChildren, getFileNode, createFileDownload | |
| Workflows | listWorkflowDefinitions, getWorkflowDefinition, listWorkflowRuns, getWorkflowRun | startWorkflowRun |
| Knowledge and inbox | retrieveKnowledge | sendInboxThreadReply |
| Webhook deliveries | listWebhookDeliveries, getWebhookDelivery | |
| Webhook destinations | listWebhookDestinations, getWebhookDestination | createWebhookDestination, updateWebhookDestination, deleteWebhookDestination, rotateWebhookDestinationSecret |
| Webhook endpoints | listWebhookEndpoints, getWebhookEndpoint | createWebhookEndpoint, updateWebhookEndpoint, deleteWebhookEndpoint, rotateWebhookEndpointSecret, rotateWebhookEndpointToken |
| Audit log | listOrganizationAuditEvents, getOrganizationAuditExport | createOrganizationAuditExport |
createFileDownload returns a signed download URL and validatePromotion checks a promotion code without changing anything, so both count as read tools. Operations that are not in this table are only available through the REST API.
Mutation tools that map to an action in the approval catalog run the organization's approval policy before they call the API. Order, shipment and purchase order mutations run the policy inside the REST route instead, so one call raises one request.
When a policy holds the call, the tool fails with code APPROVAL_REQUIRED, an approvalId, a requirement (confirm or authorize) and the approverPermission when one applies. Tell the user who has to act, and call the same tool with the same input once the request is approved. See Approvals and Errors.
A failed tool call returns isError: true. Its structuredContent is the REST problem details document, and the text content is the same document as JSON, so the code values match the API.
Each organization-scoped tool call counts once on the organization's MCP usage meter. The REST request the tool makes is not counted again as an API request.
Not yet available: MCP Apps resources, prompts and interactive widgets. The product server exposes tools only.
| Symptom | Likely cause |
|---|---|
401 Unauthorized on connect | No bearer token, an expired token, or a token whose audience the server does not accept. |
OAuth scope ... is required for this MCP tool | The token lacks mcp:read or mcp:write. |
Tool error ORGANIZATION_PERMISSION_DENIED | Your user lacks the organization permission for that operation. |
Tool error APPROVAL_REQUIRED | An approval policy holds the mutation. Retry after it is approved. |
| OAuth discovery fails | /.well-known/oauth-protected-resource is unreachable or the authorization server is misconfigured. |
| Local connection fails | The API app is not running on https://api.localhost. Start it with pnpm dev:api:portless. |
Last updated on
Webhooks
Send signed CentraKit events to your HTTPS endpoints and receive external webhooks that start workflows, including signatures, secret and token rotation, delivery retries, and the REST and MCP operations.
CLI
Every centrakit CLI command and global flag, how it signs in and resolves the API base URL, its configuration files and environment variables, and how releases are packaged.