Skip to content
Faldaro
All guides

MCP server

Faldaro hosts a Model Context Protocol server, so Claude and other MCP clients can operate your account as tool calls — authenticated by an API key, bounded by that key's privileges, metered like ordinary API traffic.

Connecting

The server speaks MCP's Streamable HTTP transport at https://faldaro.app/api/mcp. Authentication is an API key sent as a bearer header — there is no separate MCP credential, no session to manage, and nothing to install for clients that can send a header. 

# Claude Code
claude mcp add --transport http faldaro https://faldaro.app/api/mcp \
  --header "Authorization: Bearer ffk_your_key_here"

Clients that only speak stdio can use a local bridge such as mcp-remote, which forwards a stdio session to a remote HTTP server and passes the header along: 

npx mcp-remote https://faldaro.app/api/mcp \
  --header "Authorization: Bearer ffk_your_key_here"

Connectors that require OAuth sign-in rather than a header — claude.ai's web connectors among them — are not supported yet.

What the tools cover

The catalog is the same one Faldaro's in-app agent uses — nearly sixty tools spanning the platform: folders and forms; reading and editing drafts, logic, workflow and appearance; publishing; submissions (create, update, evaluate, transition, assign); reports and datasets; document and notification templates; sequences; form test cases; the dashboard and the audit log. Two in-app tools do not exist here, because they cannot: navigation (no browser) and PDF import (no attachments ride an MCP call).

There are no delete or archive tools. That is a property of the catalog, not a configuration: destructive actions stay in the app, where they carry their own confirmations and a person is present.

Authorisation

Every tool call is authorised as the key that made it — the same privilege checks and the same database-enforced tenant isolation as the raw API. The server holds no credential of its own and adds no authorisation of its own, so connecting a model can never widen what the key could already do. A tool the key lacks the privilege for answers with the same refusal the API gives, returned as a readable tool result the model can relay.

Tool annotations

Tools declare their behavior in MCP's annotation vocabulary, honestly: read-only tools carry readOnlyHint; tools that replace a document (a draft save, a logic update) carry a destructive hint; creates and transitions are marked non-idempotent. A well-behaved client uses these to decide when to ask you before acting — which leads to the part worth reading twice:

Submitter content and prompt injection

Reading submissions means reading text written by whoever filled in your forms. To a language model, sufficiently adversarial text can read like instructions. Inside Faldaro's own chat, the platform enforces a guard for this — once a turn reads submitter content, mutating tools are refused for the rest of it. Over MCP the loop belongs to your client, so that guard cannot exist on the server: confirmation of mutating actions is your MCP client's job, and the annotations above are what it decides with. Practical advice: connect read-only keys for analysis work, keep write-granting keys for authoring sessions, and treat "the model read a submission, then proposed an edit" as a moment to look before approving.

Plans, and what is never charged

The MCP server is part of the Team plan and above. API keys and the raw API — /v1 and the app's own endpoints — stay on every plan, Free included: what Team adds is the model-ready toolbox, not machine access itself. On a plan without it, requests answer 402 with "code": "PLAN_LIMIT" and the plan to ask for. (Self-hosted deployments with plan enforcement off are unaffected, as with every gate.)

Tool calls never consume AI credits, on any plan — a decided position, not an oversight: credits meter Faldaro's own model spend, and over MCP the model doing the thinking is yours. What meters this surface is the request budget below and your plan's ordinary allowances for whatever the tools do.

Budget

Requests are counted per key — 120 per minute by default; deployments tune it. Over the budget, calls answer 429 with a Retry-After header and "code": "RATE_LIMITED".

Revocation

Revoking the key severs the connection immediately: the next tool call answers 401. Nothing about the MCP session survives on the server — there is no session — so there is nothing else to clean up.