Hone CRM|

MCP Documentation

AI coding toolsAPI ReferenceSDKsHome

Overview

The Model Context Protocol is an open standard that lets AI assistants (Claude, GPT, Cursor, custom agents) safely invoke external tools. The @honecrm/mcp-server package runs a Hone CRM MCP server on your own machine, with 65 tools for deals, contacts, companies, pipelines, tags, activities, insights, relationships and commitments.

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

Most setups should use the hosted server instead. It needs no install, it also has the inbox tools, and claude.ai and Claude Desktop sign in to it with your Hone CRM account. For Claude, Claude Code, Cursor and Codex, the full guide is Connect your AI tools. This page covers the npm package.

Package

@honecrm/mcp-server

Transport

JSON-RPC over stdio

Install

The server runs on Node.js 18 or later and has no native dependencies. MCP clients start it themselves with npx, so there is nothing to install first. To check that it starts, run it by hand with your key:

Run via npx (recommended)

bash
export HONECRM_API_KEY=hone_xxxx
export HONECRM_BASE_URL=https://api.honecrm.com/v1
npx -y @honecrm/mcp-server

It prints [MCP] Hone CRM MCP Server starting with 65 tools... on stderr and then waits for a client on stdin. Stop it with Ctrl+C.

Install globally

bash
npm install -g @honecrm/mcp-server

Then run honecrm-mcp in place of npx -y @honecrm/mcp-server, with the same two variables set.

Authentication

The MCP server authenticates to the Hone CRM REST API with an API key, the same keys the SDKs and CLI use. 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 setup below. Replace hone_xxxx with your API key, and 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": [
        "-y",
        "@honecrm/mcp-server"
      ],
      "env": {
        "HONECRM_API_KEY": "hone_xxxx",
        "HONECRM_BASE_URL": "https://api.honecrm.com/v1"
      }
    }
  }
}

To connect these clients to the hosted server instead, follow Connect your AI tools.

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

65 tools across 15 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. The hosted server has these and more, including the inbox tools.

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 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 and team filters
get_contactRetrieve a single contact by ID
create_contactCreate a contact; requires at least one identifier
update_contactUpdate contact fields; replaces the 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 and 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 none
set_primary_identifierMark one identifier as primary and unset primary on the others

Manage company records with firmographic enrichment.

list_companiesList companies with search, industry and 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 (the default Sales pipeline is 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 its 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; creates unknown tags
remove_entity_tagsRemove tags from a contact, deal, or company

Log and manage interactions on deals, contacts and companies.

list_activitiesList activities, filtered by deal, contact or company
get_activityRetrieve a single activity by ID
log_activityLog an activity (call, email, meeting, message, etc.)
upsert_conversationLog or update a messaging thread (email, SMS, LinkedIn, Slack and more); one row per thread
update_activityUpdate user-created activities; system-generated ones are read-only
delete_activityDelete a user-created activity

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

list_insightsList insights, filtered by priority, category, status or linked entity
get_insightRetrieve an insight by ID
create_insightCreate an insight with category, priority, and optional linked entities
update_insightAppend linked entities, bump the occurrence count, change priority or status
delete_insightDelete an insight

The relationships Hone CRM builds from your inbox, with risk and the fields it infers.

query_relationshipsList relationships, priority-ranked; filter by kind, or by risk (e.g. risk="gte:0.5")
get_relationshipRetrieve a single relationship by ID
create_relationshipCreate a relationship from a map of roles to entity IDs
update_relationshipUpdate participants, kind, or value estimate
explain_relationship_riskA written explanation of why a relationship is at risk (metered)
correct_relationship_inferencePin a human correction to an inferred field: temperature, stage, momentum, risk, cadence or next action

What was promised in email threads: who owes what to whom.

list_commitmentsList commitments, filtered by status, owner, thread or intent
get_commitmentRetrieve a single commitment by ID
create_commitmentRecord a commitment by hand
update_commitment_statusMove a commitment to a new status, or mark it as wrongly extracted

Where an email address or other identifier was seen, and how far to trust it.

get_identifier_evidenceEvery identifier on an entity, with its evidence band and the sightings behind it
record_identifier_observationRecord one sighting of an identifier: where and when it was seen
retract_identifier_observationWithdraw a sighting; the row is kept and marked withdrawn

Standing decisions that a value must not be written to a record again.

list_entity_fact_dismissalsWhat may not be written back to an entity
dismiss_entity_factKeep a value from being written to an entity again (people only, not agent keys)
lift_entity_fact_dismissalAllow a dismissed value to be written again (people only)

GitHub repository prospects, and the ideal customer profile that ranks them.

list_repo_prospectsList GitHub repository prospects, ranked by company fit and engagement
promote_prospectTurn a prospect into a tracked contact; safe to repeat
get_icpYour organization’s ideal customer profile

Your plan and the free trial. Billing is console-only, so a key bound to an agent is refused.

get_subscriptionYour plan: the tier in effect, band allowances per seat, and whether the trial is running or available
start_trialStart the no-card 7-day Pro trial; one per account (people only, not agent keys)

Environment variables

VariableRequiredDefaultDescription
HONECRM_API_KEYYesNoneAPI key used for all requests
HONECRM_BASE_URLNohttps://api.honecrm.com/v1The REST base, including /v1. Override it for staging or 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 it fully, not just the window). Then run the server by hand with the commands under Install; you should see [MCP] Hone CRM MCP Server starting with 65 tools... on stderr. If it exits with HONECRM_API_KEY environment variable is required, the key did not reach it.

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 calls the REST API at HONECRM_BASE_URL, which is api.honecrm.com unless you set it.