Dex Personal CRM

Dex is a personal CRM that helps users maintain and nurture their professional relationships. It tracks contacts, interaction history, reminders, and organizational structures (groups, tags, custom fields).

Setup — Detect Access Method

Check which access method is available, in this order:

1. MCP tools available? If dex_search_contacts and other dex_* tools are in the tool list, use MCP tools directly. This is the preferred method — skip CLI setup entirely.
2. CLI installed? Check if dex command exists (run which dex or dex auth status). If authenticated, use CLI commands.
3. Neither? Guide the user through setup.

First-Time Setup

Path A — Platform supports MCP (Claude Desktop, Cursor, VS Code, Gemini CLI, etc.):

If the user already has the Dex MCP server configured, or their platform can add MCP servers:

npx -y add-mcp https://mcp.getdex.com/mcp -y

This auto-detects installed AI clients and configures the Dex MCP server for all of them. User authenticates via browser on first MCP connection.

Path B — Install CLI:

npm install -g @getdex/cli

Works with npm, pnpm, and yarn. No postinstall scripts — the binary is bundled in a platform-specific package.

Keeping the CLI up to date:

The CLI auto-generates commands from the MCP server's tool schemas at build time. When tools are added or updated on the server, users need to update the CLI to get the new commands. If a user reports a missing command or parameter, suggest updating:

npm install -g @getdex/cli@latest

Path C — No Node.js:

Direct the user to follow the setup guide at https://getdex.com/docs/ai/mcp-server — it has client-specific instructions for Claude Desktop, Claude Code, Cursor, VS Code, and other MCP-capable clients.

Authentication

Triggered by /dex-login or on first use when not authenticated. Ask the user which method they prefer:

Option 1 — API Key:

1. User generates a key at Dex Settings > Integrations (requires Professional plan)
2. For CLI: dex auth --token dex_your_key_here
3. Key is saved to ~/.dex/api-key (chmod 600)

Option 2 — Device Code Flow (works on remote/headless machines):

Drive this flow directly via HTTP — no browser needed on the machine:

1. Request a device code:

   curl -s -X POST https://mcp.getdex.com/device/code -H "Content-Type: application/json"
   

   Response: { "device_code": "...", "user_code": "ABCD-EFGH", "verification_uri": "https://...", "expires_in": 600, "interval": 5 }

2. Show the user the user_code and verification_uri. They open the URL on any device with a browser, log in to Dex, and enter the code.

3. Poll for approval every 5 seconds:

   curl -s -X POST https://mcp.getdex.com/device/token \
     -H "Content-Type: application/json" \
     -d '{"device_code": "\x3Cdevice_code>"}'
   

   • {"error": "authorization_pending"} → keep polling
   • {"api_key": "dex_..."} → done, save the key

4. Save the API key:

   mkdir -p ~/.dex && echo "\x3Capi_key>" > ~/.dex/api-key && chmod 600 ~/.dex/api-key
   

   For CLI: dex auth --token \x3Capi_key>

For CI/automation with no human present, use the API key method with DEX_API_KEY environment variable.

Data Model

Contact
├── Emails, Phone Numbers, Social Profiles
├── Company, Job Title, Birthday, Website
├── Description (rich text notes about the person)
├── Tags (flat labels: "Investor", "College Friend")
├── Groups (collections with emoji + description: "🏢 Acme Team")
├── Custom Fields (user-defined: input, dropdown, datepicker)
├── Notes/Timeline (interaction log: meetings, calls, coffees)
├── Reminders (follow-up tasks with optional recurrence)
└── Starred / Archived status

Using Tools

MCP Mode

Call dex_* tools directly. All tools accept and return JSON.

CLI Mode

Use the dex command. CLIHub generates subcommands from MCP tool names (replacing _ with -):

dex dex-search-contacts --query "John"
dex dex-list-contacts --limit 100
dex dex-create-contact --first-name "Jane" --last-name "Doe"
dex dex-list-tags
dex dex-create-reminder --text "Follow up" --due-at-date "2026-03-15"

Use --output json for machine-readable output, --output text (default) for human-readable.

Run dex --help for all commands, or dex \x3Ccommand> --help for command-specific help.

See CLI Command Reference for the full mapping table of all 38 tools to CLI commands.

Core Workflows

1. Find a Contact

search → get details (with notes if needed)

• Search by name, email, company, or any keyword
• Use empty query to browse recent contacts (sorted by last interaction)
• Use dex_list_contacts for bulk iteration (up to 500 per page, cursor-paginated)
• Include include_notes: true when user needs interaction history

2. Add a New Contact

create contact → (optionally) add to groups → apply tags → set reminder

• Create with whatever info is available (no fields are strictly required)
• Immediately organize: add relevant tags and groups
• Set a follow-up reminder if the user just met this person

Bulk import (CSV, spreadsheet, list):

batch create contacts → add to group → create note for all

• Use dex_create_contact with the contacts array (up to 100 per call) for batch creation
• Use the returned contact IDs to add them all to a group with dex_add_contacts_to_group
• Use dex_create_note with contact_ids to log a shared note across all imported contacts

3. Log an Interaction

(optional) list note types → create note on contact timeline

• Discover note types first with dex_list_note_types to pick the right one (Meeting, Call, Coffee, Note, etc.)
• Set event_time to when the interaction happened, not when logging it
• Keep notes concise but capture key details, action items, and personal context
• Use contact_ids (plural) to link a single note to multiple contacts (e.g. a group meeting)

4. Set a Reminder

create reminder → (link to contact if applicable)

• Always require due_at_date (ISO format: "2026-03-15")
• Use text for the reminder description — there is no separate title field
• Recurrence options: weekly, biweekly, monthly, quarterly, biannually, yearly

5. Organize Contacts

Tags — flat labels for cross-cutting categories:

create tag → add to contacts (bulk)

Groups — named collections with emoji and description:

create group → add contacts (bulk)

Best practice: Use tags for attributes ("Investor", "Engineer", "Met at Conference X") and groups for relationship clusters ("Startup Advisors", "Book Club", "Acme Corp Team").

6. Manage Custom Fields

list fields → create field definition → batch set values on contacts

• Three field types: input (free text), autocomplete (dropdown with options), datepicker
• Use dex_set_custom_field_values to set values on multiple contacts at once
• For autocomplete fields, provide categories array with the allowed options

7. Meeting Prep

When a user says "I have a meeting with X":

1. Search for the contact
2. Get full details with include_notes: true
3. Check recent reminders for pending items
4. Summarize: last interaction, key notes, pending follow-ups, shared context
5. See CRM Workflows for detailed meeting prep guidance

8. Merge Duplicates

search for potential duplicates → confirm with user → merge

• First ID in each group becomes the primary — all other data merges into it
• Always confirm with the user before merging (destructive operation)
• Can merge multiple groups in a single call

Important Patterns

Pagination

List operations use cursor-based pagination:

• dex_list_contacts: default 100 per page, max 500
• dex_search_contacts: default 50 per page, max 200
• Other list tools: default 10 per page
• Check has_more in response
• Pass next_cursor from previous response to get next page
• Iterate until has_more: false to get all results

Destructive Operations

Always confirm with the user before:

• Deleting contacts (dex_delete_contacts)
• Merging contacts (dex_merge_contacts)
• Deleting tags, groups, notes, reminders, or custom fields

Response Truncation

Responses are capped at 25,000 characters. If truncated, the response preserves pagination metadata (next_cursor, has_more) so you can fetch the next page. Use smaller limit values if responses are being truncated.

Date Formats

• All dates: ISO 8601 strings (e.g., "2026-03-15", "2026-03-15T14:30:00Z")
• Birthdays: YYYY-MM-DD
• Reminder due dates: YYYY-MM-DD

Detailed References

• Tool Reference — Complete parameter documentation for every tool, with examples
• CLI Command Reference — Full MCP tool → CLI command mapping table (only needed for CLI mode)
• CRM Workflows — Relationship management best practices, follow-up cadences, and strategies for being an effective CRM assistant