Developers

Connect your AI tools to Hone CRM

Hone CRM runs a hosted Model Context Protocol (MCP) server. Connect Claude, Claude Code, Cursor or Codex to it and your assistant can read what Hone CRM builds from your inbox: the people you talk to, who has gone quiet, and what was promised in your email threads. This page covers setup for each tool, then one task end to end.

Before you start

• A Hone CRM account with Gmail connected. Hone CRM builds people, threads and commitments from your mailbox, so there is nothing to ask about until the first import finishes. Create a free account.
• The server URL for every tool below: https://api.honecrm.com/mcp
• A way to sign in. claude.ai and Claude Desktop sign in with your Hone CRM account. Claude Code, Cursor and Codex use an API key: in Hone CRM, open Settings, then Developer, then API Keys, create a key and pick the Read-only preset. It covers everything on this page, including substrate:read and commitments:read. Keys start with hone_ and are shown once.

Claude (claude.ai and Claude Desktop)

Add Hone CRM as a custom connector. It signs in with OAuth, so no API key is involved.

1. In Claude, open Customize, then Connectors, and choose Add custom connector. On a Team or Enterprise plan, an Owner adds it under Organization settings, then Connectors.
2. For the server URL, enter https://api.honecrm.com/mcp
3. Under OAuth client (in some versions of the dialog this is under Advanced settings), choose Use your own OAuth client and enter the client ID for Hone CRM. Leave the client secret blank.
   OAuth client ID

   blepvubd0g7d80dej614534l8

4. Click Add, then Connect, and sign in with your Hone CRM account.

The connector then works in claude.ai and in Claude Desktop. The client ID step exists because Hone CRM does not support automatic client registration yet.

Claude Code

Register the hosted server with your API key in place of hone_xxxx:

claude mcp add --transport http honecrm https://api.honecrm.com/mcp \
  --header "Authorization: Bearer hone_xxxx"

Run claude mcp list to check that it connects.

Cursor

Add this to ~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json in one project:

{
  "mcpServers": {
    "honecrm": {
      "url": "https://api.honecrm.com/mcp",
      "headers": {
        "Authorization": "Bearer hone_xxxx"
      }
    }
  }
}

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.honecrm]
url = "https://api.honecrm.com/mcp"
bearer_token_env_var = "HONECRM_API_KEY"

Codex sends the variable named in bearer_token_env_var as the bearer token, so the key stays out of the file. Set it in the shell you start Codex from:

export HONECRM_API_KEY=hone_xxxx

Check a key with curl

The hosted server answers plain JSON-RPC over HTTPS, so you can test a key before configuring any tool:

curl -s https://api.honecrm.com/mcp \
  -H "Authorization: Bearer hone_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_home_summary","arguments":{}}}'

The tool's answer is JSON, returned as text in result.content[0].text. HTTP 401 means the key is missing or wrong. HTTP 403 with Missing required scope means the key was created without that scope: create a new one with the Read-only preset.

Worked example: who do I owe a follow-up?

With the server connected, ask your assistant:

Using Hone CRM, who do I owe a follow-up? Look at who I haven't been in touch with lately and at promises I made in email that are still open, then draft the follow-ups. Don't send anything.

A typical run makes these calls. All of them only read.

1. get_home_summary returns needs_attention: up to five external contacts you haven't been in touch with for 30 days or more, each with a name and identifiers such as an email address.
2. query_entities with {"identifier": {"type": "email", "value": "you@yourcompany.com"}} finds your own record, so the next call can be limited to your promises.
3. list_commitments with {"status": "open", "owner_entity_id": "<your id>"} returns the commitments you made that are still open, such as sending a document or setting up a meeting. Hone CRM finds these in your email threads. Each one has a subject, the person it was made to (obligee_entity_id) and, when one was mentioned, a deadline (due_before).
4. query_threads with {"participant_entity_id": "<their id>", "limit": 1} fetches the most recent conversation with each person, so a draft can pick up where you left off.

The assistant then writes the drafts in the conversation. Nothing is sent and nothing in Hone CRM changes. The server also has a send_email tool that sends real email, which is why the prompt says not to send.

Running the server locally

The @honecrm/mcp-server package from npm runs on your machine over stdio, with the same API key. It works with deal, contact and company records. The inbox tools in the example above (get_home_summary, query_entities and query_threads) exist only on the hosted server, so use one of the hosted setups for the example.

{
  "mcpServers": {
    "honecrm": {
      "command": "npx",
      "args": [
        "-y",
        "@honecrm/mcp-server"
      ],
      "env": {
        "HONECRM_API_KEY": "hone_xxxx",
        "HONECRM_BASE_URL": "https://api.honecrm.com/v1"
      }
    }
  }
}

This is the stdio format for Claude Desktop's claude_desktop_config.json and for Cursor's mcp.json. The MCP server docs list the config file locations and the package's tools, and the API docs cover the REST endpoints the same key can call.