The MCP server

Formule exposes a Model Context Protocol server, so an AI assistant can work with your agency’s data directly — finding leads, reading a lead’s history, updating a status, scheduling a follow-up.

https://mcp.formule.io

The one thing to understand

Every tool call runs as you.

The server does not hold a privileged key that reads whatever it likes. It resolves who you are, then queries the database as that person, under the same row-level security the app uses. An agent’s assistant sees that agent’s leads. A manager’s sees the agency’s. There is no configuration that widens this, and no service-role fallback for a user-shaped request: no user, no call.

Why this matters

It means connecting an assistant does not create a new way to leak data. The blast radius of a connected client is exactly the blast radius of that person’s own login.

Who can connect

Client	Status
Claude.ai	Supported, via OAuth.
Claude Desktop	Supported, via OAuth.
MCP Inspector	Supported, for development.
Claude Code	Not yet. It redirects to a loopback address on a changing port, and the authorization server matches redirect URIs exactly.

Connecting Claude walks through the setup.

How identity works

There are two ways in, and both end in the same place: a database query made as a real Formule user.

OAuth, for interactive clients

Standard OAuth 2.1 with PKCE. Your client discovers the authorization server from the protected-resource metadata, sends you to Formule to approve the connection, and receives a token.

• Discovery — GET https://mcp.formule.io/.well-known/oauth-protected-resource returns RFC 9728 metadata naming the authorization server.
• Consent — you approve the connection on app.formule.io, signed in as yourself.
• Scope — email. Read versus write is decided by your role and by tool annotations, not by scopes. There is no “read-only token”; there is a read-only you.
• Unauthenticated requests get a 401 carrying a WWW-Authenticate header pointing at the metadata, so a well-behaved client can start the flow on its own.

Platform key plus signed chat identity

The Telegram assistant is a trusted server. It holds a platform key and, with each call, a signed identity for the chat it is serving. The server verifies the signature, resolves it to the linked Formule user, and proceeds as that user.

This is how the Telegram assistant answers about your leads without you ever handing it a password.

Treat the linking code as a credential

The one-time code that links your Telegram chat to your Formule account is what proves the chat is you. Do not forward it. It expires within minutes and works once.

What the tools do

The catalogue covers finding and reading leads, listings, matches and agents; reporting your pipeline; and writing notes, statuses, follow-ups and nudges.

Tools are annotated read-only where they are, so a client can tell which calls are safe to make without asking you first.

The full list, generated from the server source, is in Tools reference.

Where it runs

mcp.formule.io is a Cloudflare worker in front of the server. It is the connector’s public identity and the address you should configure. The underlying function also answers on its own platform URL, but that address is not the contract.

Limits worth knowing

• Scopes are not permissions. Do not design around them. Design around roles.
• Claude Code is not supported yet — see the table above.
• List results are capped per call. Ask a narrower question rather than paging for everything.