decern-mcp

DecernHQ MCP Server

mcp-name: io.github.statwonk/decern

An official Model Context Protocol (MCP) server for DecernHQ — 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:

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

Via Smithery

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

Manual / SSE Transport

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, [e-mail], came from LinkedIn. Add her to the CRM."

The agent calls submit_data_with_triage(raw_data='{"name":"Jane Doe","email":"[e-mail]","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:

{"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

# 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 or email [e-mail]
• Privacy Policy: https://decernhq.com/privacy
• Terms of Service: https://decernhq.com/terms
• License: MIT