Custify Server

npm version License: MIT MCP Compatible GitHub Stars

Connect AI tools to your Custify customer success data via the Model Context Protocol.

Query accounts, health scores, usage data, and more — or create notes, tasks, and trigger playbooks — all from within Claude, Cursor, VS Code, or any MCP-compatible AI tool.

Quick Start

Get up and running in under 2 minutes.

1. Get your API key

Go to Custify Settings > Developer > API Access and create or copy your API key.

2. Install

npx @custify/mcp-server

3. Configure your AI tool

See the Configuration section below for your specific tool.

4. Try it out

Ask your AI assistant:

How many churned accounts do I have?

Configuration

{
  "mcpServers": {
    "custify": {
      "command": "npx",
      "args": ["-y", "@custify/mcp-server"],
      "env": {
        "CUSTIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "servers": {
    "custify": {
      "command": "npx",
      "args": ["-y", "@custify/mcp-server"],
      "env": {
        "CUSTIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

claude mcp add custify -- npx -y @custify/mcp-server \
  --env CUSTIFY_API_KEY=your-api-key-here

docker run -d \
  -p 3000:3000 \
  -e CUSTIFY_API_KEY=your-api-key-here \
  ghcr.io/custifyofficial/custify-mcp:latest

https://your-server.example.com/mcp

Available Tools

Account Tools

list_accounts supports Custify's full filter system. Each filter is an object with fieldName, fieldType, filterType, and filterValue. Use list_attributes first to discover available fields.

Filter examples:

Available filter types by field type:

Contact Tools

Health & Usage Tools

Alerts & Segments

Task Tools

list_tasks uses flat, ergonomic parameters. Filters combine with AND. To resolve a tag name like "onboarding follow up" to an ID, call list_tags with category: "task". To resolve an assignee name, call list_task_filter_values (returns user IDs with names).

Filter examples:

Available status values:

Available due shortcuts: past_due, today, this_week, this_month, later. For custom ranges, supply both due_after and due_before (ISO dates). The due shortcut and the date-range pair are mutually exclusive — passing only one bound of the range is ignored.

Action Tools

Available Resources

Resources provide read-only context that AI agents can use to understand your Custify workspace:

Examples

Here are real-world examples of what you can ask your AI assistant once connected:

Querying accounts

"How many churned accounts do I have?" Uses list_accounts with a churned filter to count accounts where churned = true.

"Show me all accounts with a health score below 30" Uses list_attributes to find the health score field name, then list_accounts with a Number filter.

"Find all accounts managed by [email protected]" Uses list_accounts with a User filter on the CSM field.

"Which accounts signed up this quarter?" Uses list_accounts with a Date filter: filterType: "this_quarter" on signed_up_at.

Account deep-dives

"Give me a full summary of Acme Corp" Uses search_accounts to find Acme, then get_account, get_health_scores, get_contacts, get_usage_data, and get_segment_membership to build a comprehensive briefing.

"What segments is Acme Corp in?" Uses search_accounts to find the account ID, then get_segment_membership.

"Show me the health score trend for Acme Corp over the last month" Uses get_health_scores to find score IDs, then get_usage_trends for historical values.

Querying tasks

"What's on my plate today?" Uses list_tasks with assignee_id (your user ID) and due: "today" to pull a daily task list.

"Show me all overdue tasks tagged 'onboarding follow up' assigned to Jane" Uses list_tags with category: "task" to resolve the tag name to an ID, list_task_filter_values to resolve Jane's user ID, then list_tasks with tag_ids, assignee_id, and status: "overdue".

"What's open for Acme Corp?" Uses search_accounts to find the account ID, then list_tasks with account_id and status: "open".

Taking actions

"Create a follow-up task for Acme Corp: Review onboarding progress, due next Friday" Uses search_accounts to find Acme, then create_task with title, due date, and account ID.

"Add a note to Acme Corp: Spoke with VP of Engineering about API latency concerns" Uses search_accounts then create_note with the note body.

"Run the renewal prep playbook for Acme Corp" Uses the playbooks resource to find the playbook ID, search_accounts for the account, then run_playbook.

Discovering your data model

"What fields can I filter accounts by?" Uses list_attributes to return all available fields with their names and types.

"What segments do we have?" Reads the custify://segments resource.

"What playbooks are available?" Reads the custify://playbooks resource.

Environment Variables

Docker

Run the server as a Docker container for HTTP-based MCP clients:

docker run -d \
  --name custify-mcp \
  -p 3000:3000 \
  -e CUSTIFY_API_KEY=your-api-key-here \
  ghcr.io/custifyofficial/custify-mcp:latest

The MCP endpoint will be available at http://localhost:3000/mcp and a health check endpoint at http://localhost:3000/health.

Security

• Data flow: Your AI tool communicates with the Custify MCP server, which then makes authenticated API calls to the Custify REST API. No data is stored by the MCP server itself.
• API key handling: Your CUSTIFY_API_KEY is read from environment variables and is never logged, cached, or exposed through MCP responses. When using STDIO transport, the key stays within your local process. When using HTTP transport, ensure your deployment is behind TLS.
• Permissions: The MCP server inherits the permissions of your API key. Use a key scoped to the minimum access level your workflows require. Read-only keys will work for all read tools; write tools require a key with write permissions.
• No telemetry: The server does not collect analytics or send data to any third party.

Troubleshooting

"Error: CUSTIFY_API_KEY environment variable is required" Make sure the CUSTIFY_API_KEY environment variable is set in your MCP client configuration. Double-check for typos and ensure there are no extra spaces.

Server not connecting in Claude Desktop

1. Verify the config file path is correct for your OS.
2. Ensure you have restarted Claude Desktop after editing the configuration.
3. Check that npx is available in your system PATH.

Authentication errors (401) Your API key may be invalid or expired. Generate a new key from Custify Settings > Developer > API Access.

Permission errors (403) The endpoint may not be available for API key access. Check that your Custify account has the required permissions.

Timeout or connection errors If using HTTP transport, verify the server is running and accessible. Check that the PORT environment variable matches your deployment configuration. For STDIO transport, ensure no firewall or proxy is blocking local process communication.

Different Custify cluster? If your Custify instance is on a different cluster (e.g., EU), set CUSTIFY_API_URL to your cluster's API URL.

Docker container exits immediately Check the container logs with docker logs custify-mcp. The most common cause is a missing CUSTIFY_API_KEY environment variable.

Contributing

Contributions are welcome! To get started:

git clone https://github.com/CustifyOfficial/custify-mcp.git
cd custify-mcp-server
npm install
npm run dev

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Submit a pull request

Please open an issue first if you plan a significant change.

License

MIT - see LICENSE for details.