# DecernHQ MCP Server

[![Smithery](https://img.shields.io/badge/Smithery-Decern%20CRM-blue?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0xMiAyTDIgN2wxMCA1IDEwLTV6Ii8+PHBhdGggZD0iTTIgMTdsMTAgNSAxMC01Ii8+PHBhdGggZD0iTTIgMTJsMTAgNSAxMC01Ii8+PC9zdmc+)](https://smithery.ai/servers/decern/crm)

mcp-name: io.github.statwonk/decern

An official [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **[DecernHQ](https://decernhq.com)** — the CRM platform built for Agentic Commerce.

This server gives AI assistants and autonomous agents secure, structured access to a full CRM: contacts, deals, pipelines, tasks, activity logs, and an AI Data Janitor for lead triage. High-value operations are guarded by human-in-the-loop approval workflows.

## Features

| Category | Capabilities |
|---|---|
| **Contact Management** | Search, retrieve, and create contacts with full CRM context |
| **Pipeline Operations** | Create deals, advance stages, auto-flag high-value deals (≥ $10k) for human approval |
| **Activity Logging** | Append calls, emails, meetings, and notes to any CRM object |
| **Task Management** | Create cross-departmental tasks (executive, sales, marketing, service, content, operations) |
| **Data Triage** | Ingest raw lead data through an AI Data Janitor that standardizes UTMs, deduplicates, and cleans records |
| **Approval Workflows** | Check the status of human-in-the-loop approval requests |
| **Read-Only Resources** | Observe the full sales pipeline, contact list, ops status, and pending approvals without mutations |

## Prerequisites

- Python 3.10+
- A DecernHQ account with an active Workspace
- A Decern API Key (generate from Workspace Settings → API Keys)

## Installation

### Via Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "decern": {
      "command": "python",
      "args": ["-m", "decern_mcp"],
      "env": {
        "DECERN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Via Smithery

```bash
npx -y @smithery/cli install decernhq-mcp --client claude
```

### Manual / SSE Transport

```bash
pip install decern-mcp
uvicorn decern_mcp.mcp_server:app --host 127.0.0.1 --port 8001
```

For SSE/HTTP transport, pass the API key via the `X-Decern-Agent-Key` header on every request.

## Configuration

| Variable | Required | Description |
|---|---|---|
| `DECERN_API_KEY` | Yes | API key with agent permissions for your Decern Workspace |

## Resources (Read-Only)

The server exposes 5 MCP Resources that provide read-only context without performing mutations:

| Resource URI | Description |
|---|---|
| `decern://sales/pipeline` | All open deals with stage, value, and approval state (top 50 by value) |
| `decern://contacts/list` | Active contacts with health scores and intent signals (top 100) |
| `decern://contacts/{id}/history` | Full audit trail and activity history for a specific contact |
| `decern://ops/status` | Task counts grouped by execution state (prepared, executing, complete) |
| `decern://approvals/pending` | All pending approval requests awaiting human decision |

## Tools

The server exposes 10 tools organized by safety profile:

### Read-Only Tools (No Side Effects)

| Tool | Description |
|---|---|
| `search_contacts` | Search contacts by name, email, or role. Returns up to 20 matches. |
| `get_contact` | Retrieve full CRM details for a contact by integer ID. |
| `get_approval_status` | Check the status (pending / approved / rejected) of a human-in-the-loop approval request. |
| `get_data_health` | Get current data integrity and triage pipeline statistics. |

### Write Tools (Create / Update — Mutates CRM Data)

| Tool | Description | Safety Annotation |
|---|---|---|
| `create_contact` | Create a new contact. Requires `name`; optional `email`, `linkedin_url`, `role`. | Creates a new record. Use `search_contacts` first to avoid duplicates. |
| `create_deal` | Create a deal in the default pipeline. Optional `total_value`, `contact_id`, `account_id`. | Creates a new record. |
| `create_task` | Create a task. Supports modules: executive, sales, marketing, service, content, operations. | Creates a new record. |
| `log_activity` | Append an activity (call, email, meeting, note) to a contact, deal, or account. | Creates an immutable audit record. |
| `update_deal_stage` | Move a deal to a new pipeline stage (e.g., 'Proposal', 'Closed Won'). | **Guarded:** Deals ≥ $10,000 are intercepted and require human approval via `get_approval_status`. |
| `submit_data_with_triage` | Ingest raw JSON lead data into the AI Data Janitor triage queue. | Queues data for processing — does not directly modify CRM records. |

> **Note:** Every write operation is recorded in the immutable audit trail with `actor: "mcp:agent"`.

## Usage Examples

### 1. Finding and Reviewing a Contact

**Prompt:** *"Do we have any contacts from Acme Corp? Get me their details."*

The agent calls `search_contacts(query="Acme")`, receives a list of matches, then calls `get_contact(contact_id=42)` to retrieve full details including health score and last interaction date.

### 2. Ingesting an Inbound Lead Safely

**Prompt:** *"A new lead emailed me — Jane Doe, jane@startup.io, came from LinkedIn. Add her to the CRM."*

The agent calls `submit_data_with_triage(raw_data='{"name":"Jane Doe","email":"jane@startup.io","utm_source":"linkedin"}')`. Decern queues this for deduplication and UTM standardization before applying it to the database.

### 3. Advancing a High-Value Deal (Human-in-the-Loop)

**Prompt:** *"Move the Enterprise Expansion deal to Closed Won."*

The agent calls `update_deal_stage(deal_id=7, stage_name="Closed Won")`. Because the deal is worth $50,000, the tool returns `{"status": "PENDING_APPROVAL", "approval_id": 12}` instead of executing. The agent informs the user and can later poll `get_approval_status(approval_id=12)` to check if the human approved the change.

### 4. Logging a Sales Call

**Prompt:** *"Log that I just had a 30-minute discovery call with contact #15."*

The agent calls `log_activity(object_type="contact", object_id=15, activity_type="call", notes="30-minute discovery call. Discussed product requirements and timeline.")`.

## Error Handling

All errors are returned as JSON objects with an `error` key:

```json
{"error": "Contact 99999 not found"}
```

| Error | Cause |
|---|---|
| `Unauthorized: Missing X-Decern-Agent-Key credential` | No API key provided |
| `Unauthorized: Invalid API Key` | Invalid key or key has been revoked |
| `Unauthorized: Failed to resolve workspace` | Valid key but no associated workspace |
| `Contact/Deal/Approval not found` | Invalid ID for the requested object |
| `Stage 'X' not found. Available: [...]` | Unknown stage name; available stages are returned |

## Troubleshooting

| Symptom | Resolution |
|---|---|
| `Unauthorized` errors | Verify your `DECERN_API_KEY` is set correctly and has not been revoked. |
| `search_contacts` returns empty | The query is workspace-scoped. Ensure the contact exists in the authenticated workspace. |
| `update_deal_stage` returns `PENDING_APPROVAL` | This is expected behavior for deals ≥ $10,000. A human must approve the change in the Decern UI. Use `get_approval_status` to poll. |
| Connection timeout on SSE transport | Verify the server is running on the expected port (default 8001) and the firewall allows the connection. |

## Development

```bash
# Clone the repository
git clone https://github.com/decernhq/mcp-server.git
cd mcp-server

# Install dependencies
pip install -r requirements.txt

# Run in development mode (stdio transport)
python mcp_server.py

# Run with SSE transport
uvicorn mcp_server:app --host 127.0.0.1 --port 8001 --reload
```

## Support & Privacy

- **Support**: Open an issue on [GitHub](https://github.com/decernhq/mcp-server/issues) or email support@decernhq.com
- **Privacy Policy**: [https://decernhq.com/privacy](https://decernhq.com/privacy)
- **Terms of Service**: [https://decernhq.com/terms](https://decernhq.com/terms)
- **License**: MIT
