Claude Desktop setup

Connect ziptie.ai to Claude Desktop so Claude can look up your tracked prompts, dashboard metrics, and competitor data during conversations.

How it works

Claude Desktop's claude_desktop_config.json only loads MCP servers that run as local processes (stdio transport). To connect to a remote HTTP MCP server, such as the one at ziptie.ai, you run a small local bridge process called mcp-remote that proxies stdio messages from Claude Desktop to ziptie.ai over HTTPS. The bridge is launched via npx and stays alive only while Claude Desktop is running.

Prerequisites

• Claude Desktop installed (macOS or Windows).
• Node.js 18 or newer installed and on your PATH (provides the npx command that launches mcp-remote).
• A ziptie.ai API token with at least read scope. Create one under Project Settings > API & MCP access. The workspace needs the paid API & MCP access add-on active first - without it the create button is disabled and existing tokens are rejected with API_ADDON_INACTIVE. See authentication.

Configuration

Open Claude Desktop settings, navigate to Developer > Edit Config, and add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "ziptie": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.ziptie.ai/mcp",
        "--header",
        "Authorization: Bearer ${ZIPTIE_TOKEN}"
      ],
      "env": {
        "ZIPTIE_TOKEN": "zt_live_<your-token>"
      }
    }
  }
}

Replace zt_live_<your-token> with your actual token value.

Why the ${ZIPTIE_TOKEN} indirection: on Windows, Claude Desktop has a known issue where literal spaces inside an args element can be mangled when invoking npx. Keeping the token in the env map and referencing it with ${ZIPTIE_TOKEN} inside the header argument sidesteps this and also keeps the token out of process listings on macOS.

Restart Claude Desktop

After saving the config file, quit and relaunch Claude Desktop fully (not just close the window - quit from the menu or system tray). The ziptie.ai tools appear in the tool picker (hammer icon) when you start a new conversation. The first launch may take a few seconds while npx downloads mcp-remote into its cache.

Verify the connection

In a new Claude conversation, ask:

"List my ziptie.ai prompts for project PROJECT_ID"

Claude will call the list_prompts tool and display the results.

Troubleshooting

"spawn npx ENOENT" or "command not found" Node.js is not installed or npx is not on your PATH. Install Node.js 18+ from nodejs.org, then fully restart Claude Desktop so it picks up the updated PATH.

"Authorization failed", or -32001 in the bridge log The token is expired, revoked, or was not copied correctly. Create a new token under Project Settings > API & MCP access (or Workspace Settings > API & MCP access for a workspace token) and update the ZIPTIE_TOKEN value in the config. The transport call itself succeeds with HTTP 200, so mcp-remote reports this as a JSON-RPC error rather than an authorization status.

-32004 with data.code API_ADDON_INACTIVE or PAYMENT_REQUIRED in the bridge log The token is valid; the workspace is not entitled. API_ADDON_INACTIVE means the API & MCP access add-on is off - it lapsed, or the subscription was cancelled - and PAYMENT_REQUIRED means the subscription payment is overdue. Entitlement is checked before any tool runs, so mcp-remote fails during the handshake and no tools appear. Fix it in workspace billing settings; the token itself does not need replacing. See MCP overview.

Empty tool list after restart Check that the JSON has no trailing commas and that the env value starts with zt_live_. Open Claude Desktop's developer log (Help > View Logs, or check the file at ~/Library/Logs/Claude/mcp-server-ziptie.log on macOS / %APPDATA%\Claude\logs\mcp-server-ziptie.log on Windows) for the exact error from mcp-remote.

"configuration is incorrect" before any tool runs Make sure you are using the command/args shape shown above, not the type: http + url + headers shape used by Claude Code or VS Code. Claude Desktop's config file does not accept that shape.

Tools do not appear in the picker Claude Desktop requires a restart after config changes. Quit fully (not just close the window) and relaunch.