affinity-mcp-workflows

Affinity MCP Workflows

Prerequisites

The MCP server requires the xaffinity CLI to be installed:

pip install "affinity-sdk[cli]"

The CLI must be configured with an API key before the MCP server will work.

⚠️ REQUIRED WORKFLOW - Do Not Skip Steps

You MUST complete steps 1-2 before running ANY queries or commands.

Skipping these steps leads to incorrect or inefficient queries because:

• discover-commands has each command's exact flags, limits and examples; this skill shows the shape of a call, not every flag
• The data model has nuances (e.g., list export vs company ls) that you'll miss

Mandatory Pre-Flight Checklist

Before proceeding to execute any commands:

1. ✅ Read xaffinity://data-model using read-xaffinity-resource
2. ✅ Run discover-commands for your specific task
3. ✅ State what you learned from each step before continuing

Example:

"I read the data-model resource and learned that list entries have custom fields
accessed via fields.<Name>. I ran discover-commands for 'interaction' and found
that interaction ls supports --type all to fetch all types in one call, and
--days to limit the time range. Now I'll proceed with..."

IMPORTANT: Write Operations Only After Explicit User Request

Only use tools or prompts that modify CRM data when the user explicitly asks to do so.

Write operations include:

• Tools: execute-write-command
• Prompts: log-interaction-and-update-workflow, change-status, log-call, log-message

Read-only operations (search, lookup, briefings) can be used proactively to help the user. But never create, update, or delete CRM records unless the user specifically requests it.

Full Scan Protection

The MCP gateway caps how much a command may fetch:

• Without --max-results a list command returns its first page and a nextCursor. Pass the number you need, up to the command's max (discover-commands → limitConfig, e.g. note feed 200); above the max is refused.
• --all is refused, except field history-bulk --all --strategy field (dry run first). To get more, pass --cursor with the previous nextCursor.
• Large results are trimmed to fit; the result says how many rows were kept, and drops nextCursor (it would skip the trimmed rows): re-run with a smaller --max-results.