Quickstart: Claude Code

Claude Code (the official CLI) talks to MCP servers natively. One command adds Pipeworx.

Install

claude mcp add pipeworx -- npx -y mcp-remote https://gateway.pipeworx.io/mcp

That’s it. Open a Claude Code session in any directory, and Pipeworx tools are available.

Verify

claude mcp list
# pipeworx — connected, 1,200+ tools

In a session:

List my recent tools, then use Pipeworx to fetch FRED MORTGAGE30US.

Claude calls ask_pipeworx or fred_get_series and returns the live value.

Per-pack install (lighter context)

For tighter context, install one pack at a time instead of the full gateway:

claude mcp add pipeworx-fred -- npx -y mcp-remote https://gateway.pipeworx.io/fred/mcp
claude mcp add pipeworx-edgar -- npx -y mcp-remote https://gateway.pipeworx.io/edgar/mcp

Each pack-scoped connection only exposes that pack’s tools.

Per-task install

Or scope by task at the URL:

claude mcp add pipeworx-housing -- npx -y mcp-remote "https://gateway.pipeworx.io/mcp?task=housing+market"

The gateway pre-filters to ~20 housing-relevant tools at connect time.

Update

claude mcp remove pipeworx
claude mcp add pipeworx -- npx -y mcp-remote https://gateway.pipeworx.io/mcp

The gateway is queried fresh on every session, so the available tool list always reflects current gateway state — no client-side cache to flush.

Troubleshooting

mcp-remote not found. It’s an npx package, not a global install. The -y flag auto-confirms the download.

Connection error. Test directly:

curl -X POST https://gateway.pipeworx.io/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 500

If this fails, network/DNS — not Claude Code.

MCP server shows “failed” in /mcp. Usually an npx cache corruption — one of mcp-remote’s files didn’t download fully and the cached package is half-installed. Symptom: claude --debug shows ERR_MODULE_NOT_FOUND against a chunk-XXXX.js under ~/.npm/_npx/. Fix:

# Drop the cache slot for mcp-remote (npx will redownload cleanly on next invocation)
rm -rf ~/.npm/_npx/*/node_modules/mcp-remote

Then Cmd+Q Claude Code and relaunch.

Why this happens. Older config snippets used mcp-remote@latest, which forces a separate npx cache slot per resolve and made corruption sticky. Current config uses bare mcp-remote (no @latest), which reuses one stable slot and is generally robust. If you copied an older config from a third-party tutorial, replacing mcp-remote@latest with mcp-remote is worth doing once.

“tools fetch failed” but server shows connected. Two known causes: (1) full gateway.pipeworx.io/mcp returns ~1,500 tool definitions in one response, which some clients can’t parse. Switch to gateway.pipeworx.io/pipeworx-catalog/mcp (17 meta-tools, agent expands on demand) or a specific pack endpoint (e.g., /edgar/mcp). (2) Outdated client validating outputSchemas strictly — if you’re on an old Claude Code build, update.

Power-user note

Claude Code reads the gateway’s serverInstructions on initialize and surfaces them to the model as a system-level briefing. So Claude already knows about ask_pipeworx, discover_tools, resolve_entity, compare_entities, and the prompt playbooks before you ask. Most agents call these without being told.