Affinity MCP Workflows
This skill covers the xaffinity MCP server tools, prompts, and resources for working with Affinity CRM.
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.
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:
set-workflow-status, update-workflow-fields, add-note, log-interaction, 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.
Available Tools
Search & Lookup (read-only)
| Tool |
Use Case |
find-entities |
Search persons, companies, opportunities by name/email |
find-lists |
Find Affinity lists by name |
get-entity-dossier |
Comprehensive entity info (details, relationship strength, interactions, notes, list memberships) |
read-xaffinity-resource |
Access dynamic resources via xaffinity:// URIs |
Workflow Management
| Tool |
Use Case |
get-list-workflow-config |
Get workflow config (statuses, fields) for a list |
get-workflow-view |
Get items from a saved workflow view |
resolve-workflow-item |
Resolve entity to list entry ID (needed before status updates) |
set-workflow-status |
(write) Update workflow item status - requires explicit user request |
update-workflow-fields |
(write) Update multiple fields on workflow item - requires explicit user request |
Relationships & Intelligence
| Tool |
Use Case |
get-relationship-insights |
Relationship strength scores, warm intro paths via shared connections |
get-status-timeline |
Status change history for a workflow item |
get-interactions |
Interaction history (calls, meetings, emails) for an entity |
Logging (write operations - require explicit user request)
| Tool |
Use Case |
add-note |
(write) Add note to a person, company, or opportunity |
log-interaction |
(write) Log call, meeting, email, or chat message |
CLI Gateway (full CLI access)
For operations not covered by specialized tools, use the CLI Gateway:
| Tool |
Use Case |
discover-commands |
Search CLI commands by keyword (e.g., "create person", "export list") |
execute-read-command |
Execute read-only CLI commands (get, search, list, export) |
execute-write-command |
(write) Execute write CLI commands (create, update, delete) |
Usage pattern:
- Discover the right command:
discover-commands(query: "create person", category: "write")
- Execute it:
execute-write-command(command: "person create", argv: ["--first-name", "John", "--last-name", "Doe"])
Destructive commands (delete operations) require double confirmation:
- Look up the entity first using
execute-read-command to show what will be deleted
- Ask the user in your response by showing them the entity details and requesting confirmation
- Wait for user's next message - do NOT proceed until they explicitly confirm
- Only after user confirms should you execute with
confirm: true
Example flow:
User: "Delete person 123"
You: execute-read-command(command: "person get", argv: ["123"])
You: "This will permanently delete John Smith (ID: 123, email: john@example.com).
Type 'yes' to confirm deletion."
[Stop here and wait for user's response]
User: "yes"
You: execute-write-command(command: "person delete", argv: ["123"], confirm: true)
Note: This is conversation-based confirmation - you ask, then wait for the user's next message. This works with all MCP clients regardless of elicitation support. The confirm: true parameter bypasses the CLI prompt, but you must get explicit user confirmation in the conversation first.
MCP Prompts (Guided Workflows)
These prompts provide guided multi-step workflows. Suggest them when appropriate.
Note: Prompts marked with (write) modify CRM data - only use when user explicitly requests.
| Prompt |
Type |
When to Suggest |
prepare-briefing |
read-only |
User has upcoming meeting, needs context on a person/company |
pipeline-review |
read-only |
User wants weekly/monthly pipeline review |
warm-intro |
read-only |
User wants to find introduction path to someone |
interaction-brief |
read-only |
Get interaction history summary for an entity |
log-interaction-and-update-workflow |
write |
User explicitly asks to log a call/meeting and update pipeline |
change-status |
write |
User explicitly asks to move a deal to new stage |
log-call |
write |
User explicitly asks to log a phone call |
log-message |
write |
User explicitly asks to log a chat/text message |
How to Invoke Prompts
Prompts are invoked with arguments. Example:
prepare-briefing(entityName: "John Smith", meetingType: "demo")warm-intro(targetName: "Jane Doe", context: "partnership discussion")log-interaction-and-update-workflow(personName: "Alice", interactionType: "call", summary: "Discussed pricing")
Resources
Access dynamic data via xaffinity:// URIs using read-xaffinity-resource:
| URI |
Returns |
xaffinity://me |
Current authenticated user details |
xaffinity://me/person-id |
Current user's person ID in Affinity |
xaffinity://interaction-enums |
Valid interaction types and directions |
xaffinity://saved-views/{listId} |
Saved views available for a list |
xaffinity://field-catalogs/{listId} |
Field definitions for a list |
xaffinity://workflow-config/{listId} |
Workflow configuration for a list |
Common Workflow Patterns
Before a Meeting
find-entities to locate the person/companyget-entity-dossier for full context (relationship strength, recent interactions, notes)- Or use:
prepare-briefing prompt for a guided flow
After a Call/Meeting
log-interaction to record what happenedresolve-workflow-item to get list entry ID (if updating pipeline)set-workflow-status if deal stage changed- Or use:
log-interaction-and-update-workflow prompt
Finding Warm Introductions
find-entities to locate target personget-relationship-insights for connection paths- Or use:
warm-intro prompt for guided flow
Pipeline Review
find-lists to locate the pipeline listget-workflow-view to see items in a saved view- Or use:
pipeline-review prompt
Updating Deal Status
find-entities to find the opportunityresolve-workflow-item to get list entry IDget-list-workflow-config to see available statusesset-workflow-status to update- Or use:
change-status prompt
Tips
- Entity types:
person, company, opportunity
- Interaction types:
call, meeting, email, chat_message, in_person
- Dossier is comprehensive:
get-entity-dossier returns relationship strength, interactions, notes, and list memberships in one call
- Resolve before update: Always use
resolve-workflow-item before set-workflow-status or update-workflow-fields
- Check workflow config: Use
get-list-workflow-config to discover valid status options before updating
1---2name: affinity-mcp-workflows3description: Use when working with Affinity CRM via MCP tools - find entities, manage workflows, log interactions, prepare briefings, find warm intros. Also use when user mentions "pipeline", "deals", "relationship strength", or wants to prepare for meetings.4---5
6# Affinity MCP Workflows
7
8This skill covers the xaffinity MCP server tools, prompts, and resources for working with Affinity CRM.
9
10## Prerequisites
11
12The MCP server requires the xaffinity CLI to be installed:
13
14```bash
15pip install "affinity-sdk[cli]"
16```
17
18The CLI must be configured with an API key before the MCP server will work.
19
20## IMPORTANT: Write Operations Only After Explicit User Request
21
22**Only use tools or prompts that modify CRM data when the user explicitly asks to do so.**
23
24Write operations include:
25- **Tools**: `set-workflow-status`, `update-workflow-fields`, `add-note`, `log-interaction`, `execute-write-command`
26- **Prompts**: `log-interaction-and-update-workflow`, `change-status`, `log-call`, `log-message`
27
28Read-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.
29
30## Available Tools
31
32### Search & Lookup (read-only)
33
34| Tool | Use Case |
35|------|----------|
36| `find-entities` | Search persons, companies, opportunities by name/email |
37| `find-lists` | Find Affinity lists by name |
38| `get-entity-dossier` | Comprehensive entity info (details, relationship strength, interactions, notes, list memberships) |
39| `read-xaffinity-resource` | Access dynamic resources via `xaffinity://` URIs |
40
41### Workflow Management
42
43| Tool | Use Case |
44|------|----------|
45| `get-list-workflow-config` | Get workflow config (statuses, fields) for a list |
46| `get-workflow-view` | Get items from a saved workflow view |
47| `resolve-workflow-item` | Resolve entity to list entry ID (needed before status updates) |
48| `set-workflow-status` | **(write)** Update workflow item status - requires explicit user request |
49| `update-workflow-fields` | **(write)** Update multiple fields on workflow item - requires explicit user request |
50
51### Relationships & Intelligence
52
53| Tool | Use Case |
54|------|----------|
55| `get-relationship-insights` | Relationship strength scores, warm intro paths via shared connections |
56| `get-status-timeline` | Status change history for a workflow item |
57| `get-interactions` | Interaction history (calls, meetings, emails) for an entity |
58
59### Logging (write operations - require explicit user request)
60
61| Tool | Use Case |
62|------|----------|
63| `add-note` | **(write)** Add note to a person, company, or opportunity |
64| `log-interaction` | **(write)** Log call, meeting, email, or chat message |
65
66### CLI Gateway (full CLI access)
67
68For operations not covered by specialized tools, use the CLI Gateway:
69
70| Tool | Use Case |
71|------|----------|
72| `discover-commands` | Search CLI commands by keyword (e.g., "create person", "export list") |
73| `execute-read-command` | Execute read-only CLI commands (get, search, list, export) |
74| `execute-write-command` | **(write)** Execute write CLI commands (create, update, delete) |
75
76**Usage pattern:**
77
781. **Discover** the right command: `discover-commands(query: "create person", category: "write")`
792. **Execute** it: `execute-write-command(command: "person create", argv: ["--first-name", "John", "--last-name", "Doe"])`
80
81**Destructive commands** (delete operations) require double confirmation:
82
831. **Look up the entity first** using `execute-read-command` to show what will be deleted
842. **Ask the user in your response** by showing them the entity details and requesting confirmation
853. **Wait for user's next message** - do NOT proceed until they explicitly confirm
864. **Only after user confirms** should you execute with `confirm: true`
87
88Example flow:
89```
90User: "Delete person 123"
91You: execute-read-command(command: "person get", argv: ["123"])
92You: "This will permanently delete John Smith (ID: 123, email: john@example.com).
93 Type 'yes' to confirm deletion."
94[Stop here and wait for user's response]
95
96User: "yes"
97You: execute-write-command(command: "person delete", argv: ["123"], confirm: true)
98```
99
100**Note**: This is conversation-based confirmation - you ask, then wait for the user's next message. This works with all MCP clients regardless of elicitation support. The `confirm: true` parameter bypasses the CLI prompt, but you must get explicit user confirmation in the conversation first.
101
102## MCP Prompts (Guided Workflows)
103
104These prompts provide guided multi-step workflows. Suggest them when appropriate.
105
106**Note**: Prompts marked with (write) modify CRM data - only use when user explicitly requests.
107
108| Prompt | Type | When to Suggest |
109|--------|------|-----------------|
110| `prepare-briefing` | read-only | User has upcoming meeting, needs context on a person/company |
111| `pipeline-review` | read-only | User wants weekly/monthly pipeline review |
112| `warm-intro` | read-only | User wants to find introduction path to someone |
113| `interaction-brief` | read-only | Get interaction history summary for an entity |
114| `log-interaction-and-update-workflow` | **write** | User explicitly asks to log a call/meeting and update pipeline |
115| `change-status` | **write** | User explicitly asks to move a deal to new stage |
116| `log-call` | **write** | User explicitly asks to log a phone call |
117| `log-message` | **write** | User explicitly asks to log a chat/text message |
118
119### How to Invoke Prompts
120
121Prompts are invoked with arguments. Example:
122- `prepare-briefing(entityName: "John Smith", meetingType: "demo")`
123- `warm-intro(targetName: "Jane Doe", context: "partnership discussion")`
124- `log-interaction-and-update-workflow(personName: "Alice", interactionType: "call", summary: "Discussed pricing")`
125
126## Resources
127
128Access dynamic data via `xaffinity://` URIs using `read-xaffinity-resource`:
129
130| URI | Returns |
131|-----|---------|
132| `xaffinity://me` | Current authenticated user details |
133| `xaffinity://me/person-id` | Current user's person ID in Affinity |
134| `xaffinity://interaction-enums` | Valid interaction types and directions |
135| `xaffinity://saved-views/{listId}` | Saved views available for a list |
136| `xaffinity://field-catalogs/{listId}` | Field definitions for a list |
137| `xaffinity://workflow-config/{listId}` | Workflow configuration for a list |
138
139## Common Workflow Patterns
140
141### Before a Meeting
1421. `find-entities` to locate the person/company
1432. `get-entity-dossier` for full context (relationship strength, recent interactions, notes)
1443. **Or use**: `prepare-briefing` prompt for a guided flow
145
146### After a Call/Meeting
1471. `log-interaction` to record what happened
1482. `resolve-workflow-item` to get list entry ID (if updating pipeline)
1493. `set-workflow-status` if deal stage changed
1504. **Or use**: `log-interaction-and-update-workflow` prompt
151
152### Finding Warm Introductions
1531. `find-entities` to locate target person
1542. `get-relationship-insights` for connection paths
1553. **Or use**: `warm-intro` prompt for guided flow
156
157### Pipeline Review
1581. `find-lists` to locate the pipeline list
1592. `get-workflow-view` to see items in a saved view
1603. **Or use**: `pipeline-review` prompt
161
162### Updating Deal Status
1631. `find-entities` to find the opportunity
1642. `resolve-workflow-item` to get list entry ID
1653. `get-list-workflow-config` to see available statuses
1664. `set-workflow-status` to update
1675. **Or use**: `change-status` prompt
168
169## Tips
170
171- **Entity types**: `person`, `company`, `opportunity`
172- **Interaction types**: `call`, `meeting`, `email`, `chat_message`, `in_person`
173- **Dossier is comprehensive**: `get-entity-dossier` returns relationship strength, interactions, notes, and list memberships in one call
174- **Resolve before update**: Always use `resolve-workflow-item` before `set-workflow-status` or `update-workflow-fields`
175- **Check workflow config**: Use `get-list-workflow-config` to discover valid status options before updating
majiayu000