---
name: affinity-mcp-workflows
description: 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.
---

# 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:

```bash
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`
- **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 |

## 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
1. `find-entities` to locate the person/company
2. `get-entity-dossier` for full context (relationship strength, recent interactions, notes)
3. **Or use**: `prepare-briefing` prompt for a guided flow

### After a Call/Meeting
1. `log-interaction` to record what happened
2. `resolve-workflow-item` to get list entry ID (if updating pipeline)
3. `set-workflow-status` if deal stage changed
4. **Or use**: `log-interaction-and-update-workflow` prompt

### Finding Warm Introductions
1. `find-entities` to locate target person
2. `get-relationship-insights` for connection paths
3. **Or use**: `warm-intro` prompt for guided flow

### Pipeline Review
1. `find-lists` to locate the pipeline list
2. `get-workflow-view` to see items in a saved view
3. **Or use**: `pipeline-review` prompt

### Updating Deal Status
1. `find-entities` to find the opportunity
2. `resolve-workflow-item` to get list entry ID
3. `get-list-workflow-config` to see available statuses
4. `set-workflow-status` to update
5. **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
