---
updatedAt: 2026-08-13T16:44:35.000Z
agentTools:
  projectIndex: https://developers.rebrandly.com/llms.txt
---

# MCP troubleshooting

Solutions for common issues when setting up and using the Rebrandly MCP server.

## Before you start

Test that the MCP endpoint is reachable before debugging your client configuration. This request does not require authentication:

```bash
curl -X POST https://mcp.rebrandly.com/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
```

A successful response returns a JSON object listing available tools. If this fails, the issue is network or endpoint connectivity, not your configuration.

Once the endpoint is confirmed reachable, test your API key:

```bash
curl -X POST https://mcp.rebrandly.com/v1/mcp \
  -H "REBRANDLY_API_KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "rebrandly_list_links", "arguments": {}}, "id": 2}'
```

A 401 response means the key is invalid or missing. Verify it in your [Rebrandly dashboard](https://app.rebrandly.com/settings/api-keys).

***

## General issues

### MCP server not appearing in your AI assistant

* Fully restart your AI assistant after saving the configuration. Closing the window is not enough on most platforms.
* Confirm Node.js 20+ is installed: `node --version`
* **JSON config** (Claude Desktop, Cursor, Amazon Q): validate at [jsonlint.com](https://jsonlint.com).
* **TOML config** (Codex CLI): validate your `~/.codex/config.toml` at [toml-lint.com](https://www.toml-lint.com).
* Confirm the file is saved to the correct location for your platform. See [MCP installation](/docs/mcp-installation) for platform-specific paths.

### API key not found or 401 Unauthorized

* Check for extra spaces or quotes around the key in your configuration.
* Confirm the header format matches your platform:
  * **Gemini CLI:** `--header "REBRANDLY_API_KEY: YOUR_API_KEY"` (colon + space)
  * **Claude Desktop / Amazon Q** (supergateway): `REBRANDLY_API_KEY:YOUR_API_KEY` (no space)
  * **Cursor:** `"REBRANDLY_API_KEY": "YOUR_API_KEY"` (JSON config)
  * **Codex CLI:** `--env REBRANDLY_API_KEY=YOUR_API_KEY` (no header, use --env)
* Verify the key is active in your [Rebrandly dashboard](https://app.rebrandly.com/settings/api-keys).

### MCP server disconnecting or not responding

* If using `supergateway`, confirm `npx` resolves correctly: `npx --version`
* Try switching to `mcp-remote` as an alternative proxy. See the manual setup section under Claude in [MCP installation](/docs/mcp-installation) for syntax.

### Tools not returning expected results

* Actions via MCP are subject to the same permissions and plan limits as the Rebrandly app. Links created via MCP count toward your monthly limit.
* If a workspace-scoped action fails, confirm you have access to that workspace in your Rebrandly account.

***

## Claude Code

### ENOENT errors on installation

The `claude mcp add` command requires fully-qualified absolute paths. Environment variables like `$HOME` and `~` do not expand and will cause an ENOENT error with no explanation.

**Do this:**

```bash
claude mcp add --transport http -s user rebrandly https://mcp.rebrandly.com/v1/mcp --header "REBRANDLY_API_KEY: YOUR_API_KEY"
```

**Not this:**

```bash
claude mcp add --transport http -s user rebrandly https://mcp.rebrandly.com/v1/mcp --header "REBRANDLY_API_KEY: $REBRANDLY_API_KEY"
```

If referencing a local config file path, use the full path: `/Users/yourname/.claude.json`, not `~/.claude.json`.

### API key not recognized — env var conflict

If your project has a `.env` file containing `REBRANDLY_API_KEY`, it can conflict with the key set in `.claude.json`. Claude Code resolves API key values in this order (highest precedence first):

1. Shell environment variables
2. Project `.env` file
3. User config (`~/.claude.json`)

If the key in your `.env` is incorrect or stale, it will override your user config silently. Remove `REBRANDLY_API_KEY` from your project `.env` or ensure the value matches your active key.

***

## Still stuck?

Use the chatbot in the lower right of this page to ask questions or contact support.