# Connect an MCP client

Connect supported clients to the current authenticated HeyCrust HTTP endpoint.

## 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

1. Use `https://heycrust.com/api/mcp` with HTTP transport and Bearer authentication. HeyCrust does not offer OAuth sign-in for this endpoint.
2. Choose your client instructions below. Keep real keys out of shared project config/commits; follow the client’s private credential storage policy.
3. Restart/reconnect the client as required, discover tools and inspect the returned schemas before calling anything.
4. 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.
5. If the client cannot attach Bearer headers or use this stateless HTTP server, use another supported transport/client rather than removing authentication.

## Expected result

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:

```sh
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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## Claude Code

With `HEYCRUST_MCP_KEY` set privately, add the HTTP server:

```sh
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](https://code.claude.com/docs/en/mcp).

## 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](https://prod.cursor.com/help/customization/mcp).

## Raw HTTP

```sh
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.