MCP Server¶

The xaffinity MCP server connects any MCP-compatible AI tool to Affinity CRM.

Compatible Clients¶

MCP (Model Context Protocol) is an open standard. This server works with:

Claude Desktop (Anthropic)
ChatGPT Desktop (OpenAI)
Cursor (AI IDE)
Windsurf (AI IDE)
Zed (AI-native editor)
VS Code + GitHub Copilot
Continue (open-source AI assistant)
JetBrains IDEs (via MCP support)
Any application implementing the MCP specification

Features¶

Entity Search - Find persons, companies, opportunities
Relationship Intelligence - Strength scores, warm intro paths
Workflow Management - Update pipeline status, manage list entries
Interaction Logging - Log calls, meetings, emails
Meeting Prep - Comprehensive briefings before meetings

Prerequisites¶

Install the CLI:

pip install "affinity-sdk[cli]"

Configure your API key:

xaffinity config setup-key

Verify configuration:

xaffinity config check-key

Client Configuration¶

Add the MCP server to your client's configuration.

Claude Desktop¶

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "xaffinity": {
      "command": "/path/to/affinity-sdk/mcp/xaffinity-mcp.sh"
    }
  }
}

Cursor / Windsurf¶

Add to your MCP configuration:

{
  "mcpServers": {
    "xaffinity": {
      "command": "/path/to/affinity-sdk/mcp/xaffinity-mcp.sh"
    }
  }
}

VS Code + GitHub Copilot¶

Add to your MCP settings:

{
  "mcpServers": {
    "xaffinity": {
      "command": "/path/to/affinity-sdk/mcp/xaffinity-mcp.sh"
    }
  }
}

Generic MCP Client¶

Any MCP client can connect using:

{
  "mcpServers": {
    "xaffinity": {
      "command": "/path/to/affinity-sdk/mcp/xaffinity-mcp.sh"
    }
  }
}

Replace /path/to/affinity-sdk with your actual installation path.

Available Tools (14)¶

Search & Lookup (read-only)¶

Tool	Description
`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	Description
`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`	Update workflow item status (write)
`update-workflow-fields`	Update multiple fields on workflow item (write)

Relationships & Intelligence¶

Tool	Description
`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)¶

Tool	Description
`add-note`	Add note to a person, company, or opportunity (write)
`log-interaction`	Log call, meeting, email, or chat message (write)

Guided Workflows (8 Prompts)¶

MCP prompts provide guided multi-step workflows.

Read-Only Prompts¶

Prompt	Use Case
`prepare-briefing`	Before a meeting - get full context on a person/company
`pipeline-review`	Weekly/monthly pipeline review
`warm-intro`	Find introduction paths to someone
`interaction-brief`	Get interaction history summary for an entity

Write Prompts¶

Prompt	Use Case
`log-interaction-and-update-workflow`	After a call/meeting - log and update pipeline
`change-status`	Move a deal to a new stage
`log-call`	Quick phone call logging
`log-message`	Quick chat/text message logging

Prompt Invocation¶

Prompts accept arguments:

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/company
get-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 happened
resolve-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 person
get-relationship-insights for connection paths
Or use: warm-intro prompt for guided flow

Pipeline Review¶

find-lists to locate the pipeline list
get-workflow-view to see items in a saved view
Or use: pipeline-review prompt

Updating Deal Status¶

find-entities to find the opportunity
resolve-workflow-item to get list entry ID
get-list-workflow-config to see available statuses
set-workflow-status to update
Or use: change-status prompt

Configuration¶

Read-Only Mode¶

Restrict to read-only tools:

AFFINITY_MCP_READ_ONLY=1 ./xaffinity-mcp.sh

Cache TTL¶

Adjust cache duration (default 10 minutes):

AFFINITY_SESSION_CACHE_TTL=300 ./xaffinity-mcp.sh

Debug Mode¶

Enable debug logging:

MCPBASH_LOG_LEVEL=debug ./xaffinity-mcp.sh

Diagnostics¶

Run health check:

./xaffinity-mcp.sh doctor

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

Claude Code Installation¶

Using Claude Code? You can also install via the plugin marketplace:

/plugin marketplace add yaniv-golan/affinity-sdk
/plugin install mcp@xaffinity

This installs the MCP server automatically. See Claude Code plugins for additional Claude-specific features.