# Model Context Protocol (MCP)

Query Salfio from Claude, Cursor, and other MCP-aware clients using the same tools your team already uses.

Salfio speaks the [Model Context Protocol](https://modelcontextprotocol.io). If your AI assistant is MCP-aware — Claude Desktop, Claude.ai web, Cursor, the MCP Inspector — it can connect to `mcp.salfio.com` and use the same client/activity/dashboard data your team sees in the app.

## Walkthrough

## What you can do

Once connected, an MCP client sees a set of tools mapped 1:1 to the Salfio Public API:

- List and retrieve clients — retrieving a single client also returns its AI churn-risk assessment (`churnRiskLevel`: `high` \| `medium` \| `low`, plus `churnSignals`, short evidence sentences grounded in captured conversations) and its AI upsell-opportunity assessment (`upsellSignalsLevel`: `high` \| `medium` \| `low`, plus `upsellSignals` and `upsellServices` — the services from your catalog the signals point to, each with `serviceId` and `title`; a `high` level always comes with at least one matched service), once enough conversation data has been analyzed
- Create, update, delete clients
- Read a client's recent activities (emails + calls), or scope the search to a date range to look further back
- Write a note onto a client (recorded as a note activity, attributed to a user)
- Read the AI-generated cards (briefing, wins/traction, risks/frictions, topics) for a client
- List the organization's integrations, and list the channels a Slack integration's bot is in — the discovery step for setting up assignment rules
- Read and replace a client's assignment rules — bind a Slack channel (or another integration) to a client so its communications are assigned automatically
- Read and maintain the organization's [services catalog](/docs/services) — the services you sell, described so the assistant can spot upsell opportunities
- Read the organization summary and users

Every tool is scoped to **your organization**. Cross-tenant reads return "not found" — the same no-leak rule the REST API enforces.

## Two ways to connect

| Client | How it authenticates |
|----|----|
| **Claude.ai web, MCP connectors** | OAuth 2.1 — browser flow, no key copy-paste |
| **Claude Desktop, Cursor, Inspector** | Bearer `sk_live_…` token from the dashboard |

Pick based on what your client supports:

- [Connect from Claude.ai web](/docs/mcp/connect-claude-web) — OAuth, the recommended path for the web client.
- [Connect from Claude Desktop (and other API-key clients)](/docs/mcp/connect-claude-desktop) — paste a Salfio API key into the client config.

## Rate limits and quotas

MCP shares the **same rate-limit buckets** as the REST API: 100 requests per minute at the organization level, 50 per minute per tool. A single team can't double its quota by splitting work across REST and MCP — the buckets are deliberately unified.

See [Rate Limits](/docs/api/rate-limits) for the full policy.

## What about data written by AI?

MCP tools that write (`create_client`, `update_client`, `delete_client`, `create_note`, `set_assignment_rules`, `create_service`, `update_service`, `delete_service`) make the same changes the API would. Every mutation is subject to the usual authorization and audit trail. An **org_oauth** connection carries organization scope — suitable for a shared team assistant, as its scope isn't tied to any one user's role — but it carries no user identity at all. A tool that must attribute its write to a person therefore either asks you which one (`create_note`'s `author_user_id`) or is unavailable on that connection (`create_task_routine`, since a routine runs as its creator). See the [Claude.ai web guide](/docs/mcp/connect-claude-web) for how to pick between user-scoped and org-scoped grants.

## Related pages

- [Administrator Tools](./administrator-tools.md)
- [Agent Tools](./mcp-external-servers.md)
- [Assign a Slack channel to a client over the API](./guides-assign-slack-channel.md)
- [Authenticated health check](./api-reference-gethealth.md)
- [Authentication](./api-authentication.md)
- [Cards](./cards.md)
- [Changelog](./changelog.md)
- [Changelog](../changelog.md)
- [Connect a workspace](./getting-started-connect-workspace.md)
- [Connect an integration](./getting-started-connect-integration.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.