MCP Server

Fondaro runs a hosted Model Context Protocol (MCP) server, so any MCP-capable AI client can read and act on your CRM and property data as you. Point a client at one URL, sign in, and the assistant can list leads, log notes, move deals, and search property sources on your behalf.

The connection always acts as the signed-in user in their active organization: members reach only the leads assigned to them, and organization admins reach the whole organization. Nothing about MCP widens what an account can already do in the dashboard.

Server Endpoint

There is one endpoint. Paste it into your client exactly as written, path included and with no trailing slash:

The server speaks Streamable HTTP. It is stateless and returns JSON. Only POST carries MCP traffic; there is no separate SSE stream to configure.

Authentication

The server accepts two kinds of credentials. Most desktop and web clients use OAuth automatically. Headless scripts and clients that take a raw header use an API key.

OAuth 2.1 (recommended)

Clients that support MCP OAuth need no manual setup beyond the URL. On first connect the client discovers the authorization server, sends you to the Fondaro sign-in and consent screen, and receives a scoped access token.

• Discovery follows RFC 9728. The server publishes protected-resource metadata at:

  https://api.fondaro.com/.well-known/oauth-protected-resource/mcp/v1

• Authorization server: Fondaro's identity provider (Clerk). Dynamic client registration is enabled, and a consent screen is always shown before access is granted.

• OAuth scopes: openid profile email user:org:read. The user:org:read scope is what binds the token to your active organization. A token with no organization is rejected.

• OAuth connections receive the full tool-scope set (see Tool scopes).

API keys

An API key is a self-managed alternative for clients that connect with a static header. Keys use the prefix fdr_mcp_ followed by a random string:

Send it as a Bearer token:

curl -X POST https://api.fondaro.com/mcp/v1 \
  -H "Authorization: Bearer fdr_mcp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Key facts:

• Keys are minted per user from the dashboard (Settings, then Integrations, then Fondaro MCP). See the Fondaro MCP dashboard guide.
• The plaintext key is shown exactly once at creation and is stored only as a SHA-256 hash. If you lose it, revoke it and mint a new one.
• Each key carries a chosen subset of tool scopes, enforced fail-closed: a tool whose scope the key lacks is hidden from tools/list and denied at call time.
• Keys can have an optional expiry (1 to 3650 days) and can be revoked at any time. Members revoke their own keys; organization admins can revoke any key in the organization.

Tool scopes

Every tool declares the scope it needs. Three scopes exist:

OAuth tokens carry all three. API keys carry whatever subset you choose when minting them (omit the subset to grant all three). A key missing a tool's scope never sees that tool.

Identity and scoping

Every tool call runs as the caller, with the same access the dashboard enforces:

• Members see and touch only leads assigned to them. Lists, searches, counts, and timelines all narrow to their own leads. Reaching a lead they are not assigned to returns an access error, never another member's data.
• Organization admins operate organization-wide.
• Admin-only tools (lead assignment and organization-wide bulk status changes) are hidden from a member's tools/list entirely.
• Write tools additionally require the organization's active subscription entitlement. In an un-entitled organization the write tools are hidden and blocked; read tools stay available.

Access is bound to live organization membership, re-checked on every request behind a short role cache (about five minutes). Removing a user from the organization therefore severs both their OAuth connections and their fdr_mcp_ keys within that window, even though OAuth tokens do not otherwise expire on their own. Individual API keys can also be revoked at any time from the dashboard.

Rate limits

• Per user or key: 120 requests per 60 seconds. Exceeding it returns a structured rate-limit error with a Retry-After header.
• Portal property searches: external property portals share a daily allowance of 300 calls per organization per UTC day. Once reached, portal-backed calls return an informative error until midnight UTC; the internal MLS and connected sources (Resales Online, Zoddak, Inmobalia) stay available.

Calling tools

MCP traffic is JSON-RPC over the endpoint itself. List the available tools:

curl -X POST https://api.fondaro.com/mcp/v1 \
  -H "Authorization: Bearer fdr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a tool by name with its arguments:

curl -X POST https://api.fondaro.com/mcp/v1 \
  -H "Authorization: Bearer fdr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_leads",
      "arguments": { "limit": 10 }
    }
  }'

In practice you will rarely craft these by hand. Your MCP client renders the tools and calls them for you once connected.

Connecting clients

Cursor .cursor/mcp.json:

{
  "mcpServers": {
    "fondaro": {
      "url": "https://api.fondaro.com/mcp/v1"
    }
  }
}

The friendly dashboard guide covers these steps in more detail.

Managing keys

MCP API keys are created and revoked from the dashboard, which calls the key-management REST endpoints below. These endpoints use your normal dashboard session (a Clerk JWT), not an fdr_mcp_ key.

Request body for POST /mcp-keys:

The key field is returned only in the POST response and never again.

Tool catalogue

The server exposes 38 tools in eight groups. Reads carry crm:read or properties:read; writes carry crm:write and require the organization's subscription entitlement. The three admin-only tools are hidden from a member's tool list.

Leads

Lead assignment

Tasks

Notes

Deals

Calls (read-only)

Email (read-only)

Properties (read-only)

The property tools span the internal Fondaro MLS, the per-organization connected sources (Resales Online, Zoddak, and Inmobalia, when the organization has each integration set up), and 19 public property portals. Call list_property_sources first: it reports which sources are connected and the exact source values the other property tools accept.

Security best practices

• Treat an fdr_mcp_ key like a password. Store it in a secrets manager, never in source control.
• Grant each key only the scopes its client needs. A read-only assistant does not need crm:write.
• Use an expiry for time-limited integrations, and revoke keys you no longer use.
• Rotate a key by minting a new one, updating the client, then revoking the old one. Multiple live keys plus revoke make this zero-downtime.
• Prefer OAuth where the client supports it: the consent screen, per-connection revocation, and the organization binding are all handled for you.