Pipedrive Setup

Connect your Pipedrive CRM to Dex. This gives Dex a live view of your pipeline and the ability to push notes, activities and field updates into the deals you're working on, always after showing you exactly what it will send.

Design (read this: it shapes the setup)

• Hybrid source of truth. Pipedrive owns the canonical numbers (stage, value, probability, close date, owner, activities). Your local pipeline tracker note (default 04-Projects/Pipeline_Tracker.md, configurable via tracker_path in System/integrations/pipedrive.yaml) keeps the strategy (per-deal narrative, coverage, positioning) and defines the focus list: the deals you're actively working drive which Pipedrive deals Dex syncs.
• Confirm every write. Nothing is written to the CRM without Dex showing you the exact payload first (the write tools support dry_run previews).
• Creation is opt-in. By default Dex can only annotate and update deals that already exist. If you want Dex to be able to create deals or organisations, that is a separate, deliberate switch (writes.allow_create), because many CRMs are shared with colleagues.
• Scope = your focus list, mapped deal-by-deal in /pipeline-sync. There is no blanket auto-sync of the whole organisation.

What This Enables

• /pipeline-sync: "show me my pipeline", reconcile live CRM numbers against your tracker, flag drift, push confirmed updates.
• /week-review: reconcile sub-step surfaces deal-number drift.
• /meeting-prep: live deal context for a deal-linked company.
• /process-meetings: offers to push meeting outcomes to the deal (confirmed).
• /daily-plan: read-only nudge on stale/overdue focus deals.

Privacy & Security

• Your access token is stored in the macOS Keychain (service dex-pipedrive) on a Mac, or in the gitignored vault-root .env file (PIPEDRIVE_API_TOKEN=...) on other systems. It is never committed.
• Non-secret settings (your Pipedrive domain, stage/owner mappings) live in System/integrations/pipedrive.yaml.
• The token is never placed in .mcp.json or config.yaml (both are committed to git).
• Every write is confirm-gated. Dex uses dry_run previews so you always see the payload before it sends.

When to Run

• User types /pipedrive-setup
• User asks to connect Pipedrive / their CRM
• User wants a live pipeline view in Dex
• During /integrate-mcp if Pipedrive is mentioned

Setup Flow

Throughout this flow, Dex performs every file action for the user. They only ever paste their token into the chat; Dex does the rest.

Step 1: Check if Already Connected

1. Read System/integrations/config.yaml -> pipedrive.enabled.
2. If true, run pipedrive_status(). If it returns connected: true, jump to Reconfiguration.
3. Otherwise continue to Step 2.

Step 2: Explain What We're Setting Up

Say:

**Let's connect Pipedrive to Dex.**

You'll get a live view of your pipeline, and Dex can push notes / activities /
field updates into your deals, always showing you exactly what it'll send first.

Your local pipeline tracker stays the home of your strategy and focus list.
Pipedrive becomes the source of truth for the deal *numbers*.

**What you'll need:**
- Your Pipedrive personal API token (I'll show you where)
- About 3 minutes

**Ready?**

Wait for confirmation.

Step 3: Get the API Token + Domain

Guide the user:

To get your Pipedrive API token:

1. In Pipedrive, click your profile (top right) -> **Personal preferences**
2. Open the **API** tab
3. Copy **Your personal API token**

Also tell me your Pipedrive web address, the bit before .pipedrive.com
(e.g. if you log in at https://yourcompany.pipedrive.com, the domain is "yourcompany").

Capture:

• api_token: validate non-empty (Pipedrive tokens are ~40-character hexadecimal).
• company_domain: the subdomain only.

Step 4: Store the Token Securely

On macOS, store it in the Keychain (service dex-pipedrive, account api) as a small JSON blob so the domain travels with it:

security add-generic-password -U -s dex-pipedrive -a api \
  -w '{"api_token": "<token>", "company_domain": "<domain>"}'

On other systems (or if the Keychain write fails), append to the gitignored vault-root .env file instead:

PIPEDRIVE_API_TOKEN=<token>

Then chmod 600 .env and confirm it is gitignored (git check-ignore .env should echo the path). Never ask the user to edit files themselves.

Step 5: Register the MCP Server (idempotent)

Check .mcp.json for a pipedrive-mcp entry under mcpServers. If missing, add (note: VAULT_PATH only, no token), substituting the real vault path:

"pipedrive-mcp": {
  "type": "stdio",
  "command": "<vault path>/.venv/bin/python",
  "args": ["<vault path>/core/integrations/pipedrive/pipedrive_server.py"],
  "env": { "VAULT_PATH": "<vault path>" }
}

If already present, leave it. Tell the user the MCP server picks up the token on the next session restart.

This step is how an existing install gets Pipedrive: an update never adds a server to a vault's .mcp.json, so the entry above is added here, when the user chooses to connect.

Step 6: Enable + Test

1. Set pipedrive.enabled: true in System/integrations/config.yaml (add the pipedrive: section if it is missing).
2. Run pipedrive_status().
   • Success (connected: true): show the authenticated user's name. Continue.
   • Failure: surface the error message. Common fixes: full token copied, no trailing spaces, correct domain. Retry up to twice, then offer to come back later (leave enabled: false).

Step 7: Build Stage + Owner Mappings

These let Dex translate your tracker's language to Pipedrive ids and back.

1. Run pipedrive_list_stages() and pipedrive_list_users().
2. Propose a stage_mapping from the stage phrases used in the user's tracker to Pipedrive stage ids, and an owner_mapping from the owner names in the tracker to Pipedrive user ids. Show the proposal and let the user correct it.
3. Optionally capture per-stage default probabilities into stages: (the API does not return them, so ask the user to read them from Pipedrive's pipeline settings if they want stage-inherited probabilities).
4. Write System/integrations/pipedrive.yaml, following the commented template at System/integrations/pipedrive.yaml.example.

Leave any mapping the user is unsure about empty; reconciliation degrades gracefully without a complete map.

Step 8: Creation Permission (deliberate choice)

Ask:

One more choice: do you want Dex to be able to CREATE deals and organisations
in Pipedrive, or only update existing ones?

Default is update-only. If your Pipedrive is shared with colleagues, an
AI-created deal can be a governance problem, so most people leave this off.
Either way, every single write is previewed and only sent on your explicit yes.

• Update-only (default): leave writes.allow_create: false in pipedrive.yaml.
• Allow creation: set writes.allow_create: true and note it can be switched off again at any time.

Step 9: Capability Cascade

Tell the user what just lit up:

Pipedrive connected.

Now available:
- /pipeline-sync: live pipeline + reconcile drift vs your tracker (run this next to map your focus deals)
- /week-review now reconciles deal numbers against the CRM
- /meeting-prep pulls live deal context for deal-linked companies
- /process-meetings offers to push meeting outcomes to deals (you confirm)
- /daily-plan flags focus deals going stale

Next step: run /pipeline-sync to match your focus deals to their
Pipedrive records so the two stay in sync from here on.

Reconfiguration

If already connected and the user runs this again, offer:

1. Test: run pipedrive_status().
2. Re-enter token: repeat Step 4.
3. Rebuild mappings: re-run Step 7.
4. Change creation permission: re-run Step 8.
5. Disconnect: set pipedrive.enabled: false. Optionally delete the Keychain item (security delete-generic-password -s dex-pipedrive -a api) or the .env line. Leave the MCP entry and pipedrive.yaml in place (harmless; tools degrade gracefully).

Troubleshooting

• feature_status: off -> token missing or pipedrive.enabled not true. Re-run Steps 4-6.
• 401 -> token invalid/expired. Regenerate in Pipedrive -> Personal preferences -> API.
• 403 -> token lacks permission for that action (e.g. editing a deal owned by a colleague). Surface honestly; don't retry blindly.
• "Deal creation is disabled" -> writes.allow_create is false. That is the safe default; only flip it if the user genuinely wants Dex creating CRM records (Step 8).
• Wrong numbers -> check company_domain/base_url point at the right Pipedrive account.