Safety & Errors
Understand the guardrails protecting your data during AI execution, the JSON-RPC error formats, and eligible service plans.
Safety Guardrails
Scope-Gated Tools
The tool catalog presented to the AI client is filtered based on the API key's scopes. A read-only key cannot see or execute mutating tools.
Confirmation Token Handshake
Calling destructive or billable tools (send_message, send_campaign, delete_lead, delete_campaign) without a confirmation token returns a preview and a short-lived (5 min), single-use token. The action only runs when the token is supplied back.
Rate Limiting
SyncFlo limits API key calls to 120 requests/minute. Exceeding it returns a rate_limited error with a retry hint.
Idempotency Protection
Create endpoints accept an idempotencyKey. Repeating the same key returns the cached response rather than creating a duplicate resource.
Audit Logging
Every tool call writes a row to the tool_audit_log table (RLS-protected, owner-scoped), capturing timestamps, actions, outcomes, and latencies. No secrets are ever stored.
No Identity Spoofing
The account context is derived exclusively from the verified API key; arguments naming a different account are rejected.
Error Envelope & Codes
The SyncFlo MCP server wraps errors using the standard envelope structure:
Error JSON Response
{
"error": "Insufficient scope: requires leads:write",
"code": "forbidden"
}| Error Code | Description / Context |
|---|---|
unauthorized | API key is missing or invalid. |
forbidden | Missing the required scope or plan does not support MCP. |
not_found | The requested resource could not be found. |
validation_error | Invalid input arguments (rejected by Zod validator). |
conflict | Operation conflict (e.g., expired/invalid confirmation token). |
rate_limited | Exceeded the limit of 120 requests per minute. |
internal_error | An error occurred on the SyncFlo server. |
Example Chat Queries
Here are some prompts you can use directly with your connected AI client:
Plan Availability
MCP access is listed on the pricing details page as “MCP / AI Client Access” under the Analytics & Integrations section. It is included on the Growth and Custom tiers, but is not supported on the Starter tier.
If a tool call returns an upgrade-required forbidden error code, it indicates that the account plan does not include MCP access.
Changelog (MCP Launch Release)
POST /api/mcp— stateless JSON-RPC MCP server endpoint (supporting initialization, tool listings, execution calls, CORS, and ping checks).- MCP library modules: tool registry configuration, call-tool handler, auth parser, subscription guard, confirmation tokens, audit loggers, and error wrappers.
- New dashboard panel MCP Connect (
/dashboard/mcp) showing connectivity credentials, setup instructions, and Claude/Cursor configurations. - Added comparison matrix support for MCP / AI Client Access.
- Database migration introducing
tool_audit_logtable with row-level security (RLS).
- API Key Scopes support in dashboard with retrofitted full-access fallback.
- Unified context extraction and auth adapter via
getAccountContext. - Per-key rate limits (120/min) matching standard HTTP rate limiting response headers.
- Standardized errors envelope and codes.
- Unified cursor/offset pagination metadata on listing responses.
- Support for idempotency keys on resource creation endpoints.
- New API routes: leads detail/deletion, conversation detail, campaigns deletion, agents metadata, usage statistics, and OpenAPI OpenAPI 3.1 specification endpoint.
- Shared business logic layers under
src/lib/services/*.