API Documentation
Support

MCP troubleshooting

Before you start

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

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:

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.

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.
  • TOML config (Codex CLI): validate your ~/.codex/config.toml at toml-lint.com.
  • Confirm the file is saved to the correct location for your platform. See 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.

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 Claude Desktop section in 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:

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

Not this:

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.

Updated 1 day ago