Hone CRM|

MCP Documentation

API ReferenceSDKsHome

Overview

The Model Context Protocol is an open standard that lets AI assistants (Claude, GPT, Cursor, custom agents) safely invoke external tools. Hone CRM ships an official MCP server that exposes 43+ tools spanning every first-class entity — deals, contacts, companies, pipelines, tags, activities, insights, and more.

Point your AI client at the server once, and the model can list, create, update, and analyze CRM data on your behalf — without ever leaving the chat.

Package

@honecrm/mcp-server

Transport

JSON-RPC over stdio

Install

The server runs on Node.js ≥ 18 and has zero native dependencies. You can run it directly with npx — most MCP clients invoke it this way and no prior install is needed. For faster cold-starts you can also install globally.

Run via npx (recommended)

bash
HONECRM_API_KEY=hone_xxxx npx @honecrm/mcp-server

Install globally

bash
npm install -g @honecrm/mcp-server

HONECRM_API_KEY=hone_xxxx honecrm-mcp

Authentication

The MCP server authenticates to the Hone CRM REST API using an API key — the same keys used by the SDKs and CLI. Create one in Settings → Developer → API Keys and scope it narrowly: read-only where possible, or restricted to specific resources (deals:read, contacts:write, etc.).

Treat MCP keys like credentials. Never paste them into chat transcripts or commit them to source control. In production, store the key in a secret manager and inject it via HONECRM_API_KEY.

Tool calls inherit the API key's scopes. If a tool tries to mutate something the key isn't allowed to touch, the backend returns FORBIDDEN and the MCP server surfaces the error back to the model.

Client setup

Pick your MCP client and copy the config below. Replace hone_xxxx with your real API key. Restart the client after editing its config file.

Config location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)
json
{
  "mcpServers": {
    "honecrm": {
      "command": "npx",
      "args": ["@honecrm/mcp-server"],
      "env": {
        "HONECRM_API_KEY": "hone_xxxx"
      }
    }
  }
}

Verify it works

After restarting your client, open a new conversation and try:

“List my top 5 open deals by value using the Hone CRM MCP.”

The model should call list_deals with status: 'active', sort client-side, and report results. If you don't see the tool invocation, double-check the config file path, the API key, and your client's MCP-tool permissions.

Available tools

43 tools across 9 categories

Every tool wraps a REST endpoint on the public API. Input schemas follow JSON Schema; the full schema (types, enums, required fields) is advertised via tools/list at connection time, so modern clients show parameter docs inline.

Full CRUD on sales deals, including pipeline and stage transitions.

list_dealsList deals with optional filters (stage, status, search, teamId, pipelineId)
get_dealRetrieve a single deal by ID
create_dealCreate a new deal — name, value, contact, pipeline, stage, tags, customFields
update_dealUpdate an existing deal; stage is validated against the pipeline
delete_dealDelete a deal permanently

Manage contact records linked to deals and companies.

list_contactsList contacts with search / company / team filters
get_contactRetrieve a single contact by ID
create_contactCreate a contact — requires at least one identifier
update_contactUpdate contact fields; replaces identifiers array if provided
delete_contactDelete a contact permanently

Composite tools for managing a contact’s identifier list (email, phone, linkedin, etc.).

add_contact_identifierAppend a new identifier (normalized & deduplicated)
update_contact_identifierChange value, label, or primary status of an existing identifier
delete_contact_identifierRemove an identifier; refuses if it would leave the contact with zero
set_primary_identifierMark one identifier as primary, unset primary on all others

Manage company records with firmographic enrichment.

list_companiesList companies with search / industry / domain filters
get_companyRetrieve a single company by ID
create_companyCreate a company — name, domain, industry, website, tags, customFields
update_companyUpdate company fields
delete_companyDelete a company permanently

Create custom deal pipelines (sales, recruiting, fundraising, etc.).

list_pipelinesList all pipelines (default Sales pipeline is auto-created on first access)
get_pipelineRetrieve a single pipeline by ID
create_pipelineCreate a custom pipeline with named stages (open / won / lost)
update_pipelineRename, reorder, or add stages; removing a stage with active deals fails
delete_pipelineDelete a pipeline; use force=true to move deals to the default first

Account-level tag registry with merge and bulk-assignment.

list_tagsList all tags, optionally filtered by group
get_tagRetrieve a tag by ID
create_tagCreate a tag (name is normalized: lowercased, trimmed, spaces → dashes)
update_tagUpdate tag name, color, description, or group
delete_tagDelete a tag (requires confirm=true if in use)
merge_tagsMerge source tag into target tag; source is deleted
add_entity_tagsApply tags to a contact, deal, or company; auto-creates unknown tags
remove_entity_tagsRemove tags from a contact, deal, or company

Track recurring themes across contacts, deals, and activities (objections, feature requests, etc.).

list_insightsList insights, filter by priority / category / status / linked entity
get_insightRetrieve an insight by ID
create_insightCreate a new insight with category, priority, and optional linked entities
update_insightAppend linked entities, bump occurrence count, change priority/status
delete_insightDelete an insight

Log and manage interactions on deals and contacts.

list_activitiesList activities, filter by deal / contact / company
get_activityRetrieve a single activity by ID
log_activityLog an activity (call, email, meeting, message, etc.)
update_activityUpdate user-created activities; system-generated ones are read-only
delete_activityDelete a user-created activity

Environment variables

VariableRequiredDefaultDescription
HONECRM_API_KEYYes—API key used for all requests
HONECRM_BASE_URLNohttps://api.honecrm.com/v1Override for staging / local development

Protocol details

Transport
JSON-RPC 2.0 framed one message per line on stdio
Protocol version
2024-11-05
Capabilities
Tools only (no prompts or resources yet)
Methods
initialize, tools/list, tools/call

The server never touches your database directly — all tool calls flow through theREST APIusing the standard Authorization: Bearer header. Rate limits, scopes, and audit logging apply identically to MCP and direct API traffic.

Troubleshooting

Client doesn't list any tools

Confirm the client loaded the config (restart fully, not just the window). Run HONECRM_API_KEY=... npx @honecrm/mcp-server manually; you should see [MCP] Hone CRM MCP Server starting… on stderr.

401 / UNAUTHORIZED from tool calls

The API key is missing, revoked, or malformed. Create a new key in Settings → Developer and update the env var. Keys must start with hone_.

403 / FORBIDDEN on a specific tool

Your API key doesn't include the required scope. Either broaden the key's scopes, or create a separate key specifically for the agent.

429 / RATE_LIMIT_EXCEEDED

The agent is calling faster than your tier allows. See rate limits for the per-tier request-per-minute ceilings.

Tool hangs or times out

Check your network; the server proxies to api.honecrm.com. If you're behind a corporate proxy, set HTTPS_PROXY in the env block of your MCP client config.