Guides

Connect an MCP client

Connect supported clients to the current authenticated HeyCrust HTTP endpoint.

Verified 2026-10-07·Read Markdown

On this page

What you need

An MCP-capable client and a privately stored HeyCrust credential. The owner workspace key has broad tools; an affiliate key exposes only partner-quality reporting with all required read scopes.

Steps

Use https://heycrust.com/api/mcp with HTTP transport and Bearer authentication. HeyCrust does not offer OAuth sign-in for this endpoint.
Choose your client instructions below. Keep real keys out of shared project config/commits; follow the client’s private credential storage policy.
Restart/reconnect the client as required, discover tools and inspect the returned schemas before calling anything.
Try list_apps for an owner credential or the scoped quality report for an affiliate key. Treat setup, draft edits and delivery actions as separate consequential operations.
If the client cannot attach Bearer headers or use this stateless HTTP server, use another supported transport/client rather than removing authentication.

The visible tool catalog matches the authenticated credential. Owners have 25 tools; a scoped key has only get_affiliate_partner_quality when it includes programs:read, referrals:read and commissions:read.

Codex

Set HEYCRUST_MCP_KEY privately in the environment available to Codex, then run:

codex mcp add heycrust --url https://heycrust.com/api/mcp \
  --bearer-token-env-var HEYCRUST_MCP_KEY

The command names the environment variable; it does not place its value in this documentation. See Codex MCP instructions.

Claude Code

With HEYCRUST_MCP_KEY set privately, add the HTTP server:

claude mcp add --transport http heycrust https://heycrust.com/api/mcp \
  --header "Authorization: Bearer $HEYCRUST_MCP_KEY"

The shell expands this value into the client configuration. Keep that configuration private; do not commit a real-key project .mcp.json. See Claude Code MCP instructions.

Cursor

Use your private MCP configuration and replace the credential placeholder:

json

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

Cursor supports a global ~/.cursor/mcp.json and project configuration. Keep any configuration containing a real key private. See Cursor MCP instructions.

Raw HTTP

curl https://heycrust.com/api/mcp \
  -H "Authorization: Bearer $HEYCRUST_MCP_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

POST bodies are bounded to 1 MiB. Notifications return 202; tool/protocol results are JSON-RPC and may contain a tool-level error even with HTTP 200. The supported protocol versions are 2025-06-18, 2025-03-26 and 2024-11-05.

Troubleshooting

401: inspect credential type/value/revocation. Missing tools: inspect audience and all required scopes. GET/DELETE return 405 because messages use POST JSON-RPC; the server has no server-initiated SSE stream or sessions to delete.

Search documentation