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. Prefer MCP browser OAuth when available, then device code for an interactive CLI session, and API keys for CI or when the user explicitly chooses one.

Do not trust dex auth status alone. Status is green if any credential file exists. Verify with a real command such as dex dex-list-tags. A 401 unauthorized after a "successful" login almost always means the CLI is still reading a stale token.

Where credentials actually live:

• @getdex/cli reads ~/.clihub/credentials.json (auth_type: bearer_token, token: dex_…).
• Some docs and older agents only write ~/.dex/api-key. That file is not what the CLI sends on MCP calls.
• After device-code or API-key setup, write both files, or the next dex … call will 401.

Cloudflare: every request to mcp.getdex.com must send User-Agent: dex-cli. Bare curl with no UA returns Cloudflare 1010 (browser_signature_banned). That is not an expired code and not a Dex 401.

Never ask the user to paste an API key into chat. Do not print, log, commit, or include it in tool arguments that will be shown back to the user. dex auth --token <key> puts the secret on the process argv — do not run that from an agent.

Option 1 — API Key:

1. User generates a key at Dex Settings > Integrations (requires Professional plan)
2. Ask the user to save it in their own terminal, or write both files below from a local script that never prints the value
3. Destinations: ~/.dex/api-key (chmod 600) and ~/.clihub/credentials.json (chmod 600)

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

Drive this flow directly via HTTP — no browser needed on the machine. Always send User-Agent: dex-cli.

1. Request a device code:

   curl -s -X POST https://mcp.getdex.com/device/code \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "User-Agent: dex-cli"
   

   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 without logging the successful response:

   curl -s -X POST https://mcp.getdex.com/device/token \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "User-Agent: dex-cli" \
     -d '{"device_code": "<device_code>"}'
   

   • HTTP 200 + {"error": "authorization_pending"} → keep polling (this is not success)
   • HTTP 429 + {"error": "slow_down"} → wait longer than interval
   • HTTP 400 + {"error": "expired_token"} → request a new device code
   • HTTP 403 Cloudflare 1010 → add User-Agent: dex-cli and start over
   • HTTP 200 + api_key → stop polling. Do not print the body.

4. Save the key to both locations without printing it:

   install -d -m 700 ~/.dex ~/.clihub
   umask 077
   

   • ~/.dex/api-key — raw dex_… bytes, mode 600, no trailing commentary
   • ~/.clihub/credentials.json — mode 600, this schema (CLI source of truth):

   {
     "version": 2,
     "servers": {
       "https://mcp.getdex.com/mcp": {
         "type": "bearer",
         "auth_type": "bearer_token",
         "token": "<api_key>"
       }
     }
   }
   

   If the execution surface cannot keep the successful /device/token response out of chat or tool logs, stop and ask the user to finish in their own terminal.

5. Verify with dex dex-list-tags (or another read). If that 401s, ~/.clihub/credentials.json was not updated.

There is no dex auth login subcommand in current @getdex/cli (1.0.x) even if some READMEs mention it. Use this HTTP device flow.

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

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 <command> --help for command-specific help.

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

Core Workflows

1. Find a Contact

choose search/filter/list → get details (with notes if needed)

• Use dex_search_contacts for keywords or real geographic proximity with near and optional radius_km
• When using near, keep query for an additional non-location filter; do not repeat the place in both fields
• Use dex_filter_contacts for structured AND filters such as tags, groups, company, profile presence, dates, archived state, and custom fields
• Use dex_list_contacts for unfiltered bulk iteration (up to 500 per page, cursor-paginated)
• Use an empty search query to browse a single batch of contacts sorted by most recent interaction
• 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. Manage Follow-Ups

set cadence or create reminder → complete/snooze when due

• Use dex_update_contact.keep_in_touch for relationship cadence; use a reminder for a specific task
• 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
• Use dex_complete_keep_in_touch without snooze_days after a real interaction; use snooze_days to defer without recording a touch

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. Optionally search relevant email correspondence and fetch the calendar event when the user asks for live context
5. Summarize: last interaction, key notes, pending follow-ups, shared context, attendees, and recent correspondence
6. See CRM Workflows for detailed meeting prep guidance

8. Manage Calendar Events

• Use dex_list_calendar_events for a time window or plain-text event search across all connected Google/Microsoft accounts
• Reuse an event's returned email as account_email for get/update/delete
• For create/update/delete, also pass account_provider when the same address is connected to both providers; dex_get_calendar_event currently accepts only account_email
• For timed events, provide both start_datetime and end_datetime with explicit offsets; include an IANA timezone
• For all-day events, provide start_date; end_date is exclusive and defaults to the next day
• Confirm before creation when attendees may receive invitations
• On update, attendees replaces the whole list; fetch the event first and include everyone who should remain
• A recurring series ID updates the whole series; state that scope before confirmation
• Identical create/update retries are idempotent after a timeout

An update cannot move an event between connected accounts. To transfer one, fetch the original, confirm creating a replacement on the target account, then separately confirm deleting the original. Preserve the full attendee list and details, and warn that organizer identity, RSVP state, conferencing data, and provider notifications may change.

If a calendar write fails for missing provider scope, direct the user to Settings → Sync & Integrations → Grant calendar access for that account.

9. Search Correspondence

• Use dex_search_emails for live, read-only search across all connected Google/Microsoft mailboxes
• Use plain keywords such as a name, company, domain, or topic; provider operators such as from: and to: are neutralized
• Set after and before for precise date ranges; otherwise the search covers roughly the last six months
• Results contain metadata, snippets, and provider links, not full bodies
• Dex cannot send email; do not imply that this tool drafts or sends messages

10. Archive, Delete, or Merge

Prefer reversible cleanup:

1. Use dex_archive_contacts for contacts the user may want later
2. Find archived contacts with dex_filter_contacts and archived_only: true
3. Restore them with dex_archive_contacts and archived: false

For duplicates:

search for potential duplicates → confirm with user → merge

• Dex chooses the oldest record in each group as the survivor, regardless of input order
• Read mergedContactIds from the response to learn which ID survived
• Always confirm with the user before merging (destructive operation)
• Can merge multiple groups in a single call

11. Handle Outcome-Oriented Requests

For multi-contact or multi-step requests, follow this reusable contract:

define scope → inspect current state → preview proposed outcome → confirm writes → execute → verify

• Treat requests to analyze, recommend, audit, or prepare as read-only unless the user also asks for changes
• When the user says “all,” paginate the complete relevant dataset and state whether the scope includes active contacts, archived contacts, or both
• Reuse existing tags, groups, custom fields, contacts, and recent notes before creating anything
• Separate high-confidence actions from ambiguous records that need review
• Present exact additions, updates, removals, archives, merges, notes, and reminders before bulk writes
• Verify changed records with fresh reads and report successes, skips, and failures

Load CRM Workflows for detailed playbooks when the user asks to:

• Categorize or reorganize their whole network
• Turn a notetaker summary or transcript into notes, contact updates, and reminders
• Audit or clean up CRM data
• Import and follow up with people from an event or roster
• Review relationship health or plan outreach
• Prepare a day or week of meetings
• Build a target contact list from several criteria

Important Patterns

Privacy and Data Minimization

• Retrieve only the fields and history needed for the request; leave include_notes and include_contacts off unless relationship context is necessary
• Treat contact methods, notes, email snippets, attendee lists, and provider links as private relationship data
• Summarize relevant context instead of repeating unnecessary personal details
• Never share or transmit Dex data to another service without an explicit user request
• Do not claim access to full email bodies when dex_search_emails returns only metadata and snippets

Pagination

Only responses with has_more and next_cursor use cursor pagination:

• dex_list_contacts: default 100 per page, max 500
• dex_filter_contacts: default 50 per page, max 200
• Tag, group-contact, note, and reminder lists: 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

dex_search_contacts, dex_list_calendar_events, and dex_search_emails return a bounded single batch, not a cursor. Narrow the query or date range when necessary.

Destructive Operations

Respect MCP host confirmations. In CLI mode, explicitly summarize the target and consequence before any operation that deletes, overwrites, removes relationships, archives, completes cadence state, changes external calendar state, or may send invitations.

High-risk examples:

• Contact deletion, merge, and bulk archive
• Any update that overwrites saved fields or replaces a collection
• Removing tags or group memberships
• Completing/snoozing keep-in-touch state
• Deleting groups, tags, notes, reminders, or custom fields
• Setting custom field values in bulk
• Creating, updating, or deleting calendar events

Before a destructive call, resolve names to current IDs, read the current record when overwriting a collection, show the intended delta, and never guess ambiguous targets.

For contact cleanup, do not define “stale” from inactivity alone. Review open reminders and active relationship signals, present exact archive/retain lists, and require approval before archiving or changing cadence. Date filters exclude contacts with no recorded interaction, so review those separately when they matter.

Response Truncation

Responses are capped at 25,000 characters. Cursor-based tools preserve next_cursor and has_more; continue with a smaller page. For single-batch search, calendar, and email tools, reduce limit or narrow the query/date range.

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
• Calendar timed events: ISO 8601 with an explicit UTC offset plus an IANA timezone
• Calendar all-day end_date: exclusive

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