MCP — Postman Workspace

Postman is the easiest way to test and document Rockhopper's MCP server outside of an AI client. Use it when you want to:

• Verify a Personal Access Token works before pasting it into Cursor or Claude.

• Explore every tool, resource, and prompt with a UI rather than a chat transcript.

• Hand a customer or teammate a one-click way to try the integration.

• Compare local (stdio) and remote (HTTP) transports side by side.

This page covers installing Postman, importing the Rockhopper workspace, configuring environments, and running your first request. For setting up the MCP server in your AI client (Cursor, Claude Desktop, Claude.ai, etc.) see MCP Server (AI Integration).

Postman added a first-class MCP Request type in mid-2025, alongside REST, GraphQL, gRPC, and WebSocket. You'll need Postman Desktop v11.x or newer — older versions don't support MCP at all.

When to use Postman vs other clients

If you want to...	Use
Have an AI assistant in Cursor/Claude/VS Code call Rockhopper for you	The local npx install
Have Claude.ai or ChatGPT on the web call Rockhopper	The remote gateway
Click around tools/resources/prompts manually, see raw JSON, share with a teammate	This guide (Postman)
Inspect the protocol while developing the server itself	The MCP Inspector (engineer-only, internal use)

Collection layout

The Rockhopper MCP Server collection follows the Postman peer-vendor pattern used by PayPal, GitHub, HubSpot, and Postman's own MCP catalog:

Rockhopper MCP Server
├── Remote/
│   └── Rockhopper MCP — HTTP + PAT     ← hosted gateway, Bearer auth (PAT)
└── Local/
    └── Rockhopper MCP — Local (stdio)  ← spawns @rockhopper-co/mcp-server via npx

Both variants expose the same 16 tools / 4 prompts / 10 resources — they're two different ways to reach the same server. Pick whichever matches your environment:

Variant	When to use	Transport	What spawns
Remote — HTTP + PAT	Default. Fast, no install.	HTTPS to mcp.rockhopper.co	Nothing local — talks to our hosted gateway
Local — stdio	Behind corporate firewall; want to inspect the npm package; offline-by-default	stdio to a child process	npx -y @rockhopper-co/mcp-server on your machine (Node 20+ required)

Prerequisites

• An active Rockhopper account with at least one enrolled file (so the read tools have something to return).

• A Personal Access Token. Create one from Avatar → Access Tokens in app.rockhopper.co — see the PAT walkthrough.

• Postman Desktop v11.x or newer (download). Postman Web does support MCP requests, but the Local (stdio) variant requires the desktop app — only desktop can spawn child processes.

• Node.js 20+ on your machine — only needed for the Local (stdio) variant. Remote (HTTP) doesn't touch your machine.

Step 1 — Install and sign in

1. Install Postman Desktop and sign in with your Postman account (free tier is sufficient).

2. Confirm version: Help → About. The "Version" line should start with 11. or higher.

Step 2 — Fork the Rockhopper workspace

Easiest path: click the Run In Postman button at the top of this page. Postman Desktop opens with the collection ready to fork into a workspace of your choice. Or do it manually:

1. Open the Rockhopper MCP — Public workspace.

2. Click Fork → Fork Collection on the Rockhopper MCP Server collection. Choose your personal or team workspace as the destination.

3. Also fork the Production (template) environment — it has GATEWAY_URL pre-filled and a blank ROCKHOPPER_PAT slot for your token.

Don't use export-then-import for MCP collections. Postman's REST API and Collection v2.1 export format cannot represent MCP Request items (they're a Postman-cloud-native type, not part of the v2.1 schema). A JSON export of the collection would lose both MCP Request items entirely. Fork is the only way to preserve them.

Step 3 — Configure your environment

The collection uses two variables across both variants:

Variable	Purpose	Value
GATEWAY_URL	Where Remote requests go	https://mcp.rockhopper.co (pre-filled in template)
ROCKHOPPER_PAT	Your authentication token	Your rh_pat_… token — you fill this in

After forking the environment:

1. Click the eye icon next to the env dropdown (top-right) → Edit on your forked env.

2. Find the ROCKHOPPER_PAT row.

3. Paste your rh_pat_… token into the Current Value column (not Initial Value).

4. Click Save.

Never put a PAT in the Initial Value column. Initial Value syncs when you export or fork the environment — your PAT would leak to anyone who forks. The Current Value column stays local to your machine and never syncs.

1. Confirm the environment is active in the top-right dropdown.

Step 4 — Try the Remote variant first (fastest)

Open Remote/Rockhopper MCP — HTTP + PAT.

1. Click Load Capabilities. Postman calls initialize + tools/list + resources/list + prompts/list against the hosted gateway at {{GATEWAY_URL}}/mcp.

2. Wait ~1 second. The Tools, Resources, and Prompts tabs populate.

3. Open the Tools tab. You should see 16 tools (list_files, get_file_versions, create_version, add_comment, etc.).

4. Click list_files (it takes no arguments) → click Run.

5. The response pane shows your enrolled files as JSON.

If list_files returns your files, the Remote variant works end-to-end. You can pick any tool, fill in arguments via Postman's form UI, and click Run.

The Resources tab lets you read individual data sources (file metadata, version history, comments, etc.) by URI. The Prompts tab lets you run pre-built workflow templates.

Want to verify the gateway is reachable without auth? curl https://mcp.rockhopper.co/healthz from a terminal returns {"status":"ok"} on a live deployment. This is the only unauthenticated endpoint.

Step 5 — Try the Local (stdio) variant (optional)

This variant runs the MCP server as a child process on your machine. Useful for corporate-firewall environments where outbound HTTPS to mcp.rockhopper.co is blocked, or when you want to inspect what the npm package does.

Open Local/Rockhopper MCP — Local (stdio).

1. Confirm the Command is npx with Arguments -y @rockhopper-co/mcp-server.

2. Open the Environment tab on the request. You should see a single row:

   • Key: ROCKHOPPER_TOKEN

   • Value: {{ROCKHOPPER_PAT}} (in template-variable blue — substituted from your env at run time)

3. Click Connect (top-right, blue button). On first run, npx downloads @rockhopper-co/mcp-server from npm (~10 seconds); subsequent runs reuse the cache.

4. Status pill turns green: Connected. Now click Load Capabilities — same 16 tools / 4 prompts / 10 resources as Remote.

The env var inside the MCP Request differs from the Postman variable name. Postman variable ROCKHOPPER_PAT gets substituted into the process env var ROCKHOPPER_TOKEN, which is what @rockhopper-co/mcp-server reads (per mcp-server/src/cli.ts:9). Don't rename either side without updating both.

Self-hosted Rockhopper

If your company runs Rockhopper at a custom domain, add a second env-var row in the request's Environment tab:

Key	Value
ROCKHOPPER_TOKEN	{{ROCKHOPPER_PAT}}
ROCKHOPPER_API_URL	https://rockhopper.your-company.com

The npm package's CLI reads both. ROCKHOPPER_API_URL defaults to https://api.rockhopper.co if unset.

When to pick which variant

• Always start with Remote (HTTP + PAT) — it's fastest and exercises the same production gateway that AI clients hit.

• Switch to Local (stdio) if:

  • Your network blocks mcp.rockhopper.co.

  • You're debugging the npm package itself.

  • You want bit-for-bit reproducibility with what Cursor / Claude Desktop run locally.

Both variants share the same ROCKHOPPER_PAT env value, so you only need one PAT.

Troubleshooting

"Invalid token" / 401 on every Remote request. The PAT might be expired, revoked, or pasted with whitespace. Re-create the token from app.rockhopper.co and paste it carefully into the ROCKHOPPER_PAT env var's Current Value.

Local (stdio) shows "Couldn't run the request: MCP error -32000: Connection closed". Three usual suspects:

1. The active env's ROCKHOPPER_PAT Current Value is blank. Check the env dropdown is set to your filled env, not Production (template).

2. The env var name inside the request is wrong. Must be ROCKHOPPER_TOKEN (not ROCKHOPPER_API_TOKEN, not ROCKHOPPER_PAT) — that's the variable the npm package reads.

3. Node.js isn't on your PATH or is older than 20. Run node --version in a terminal.

Healthz passes but tools return errors. Make sure the ROCKHOPPER_PAT variable has your actual token, not a placeholder. The health endpoint doesn't require auth, but all tool calls do.

Empty responses or "No Environment". Make sure the environment dropdown (top-right) is set to your forked env, not No Environment and not a template. Postman silently swallows the request when env vars are unbound.

"Disconnected" pill won't go away on Local (stdio). Open View → Show Postman Console (Cmd+Alt+C), click Connect again, and read the stderr from the spawned child process. The mcp-server's startup errors land there.

Stuck import or duplicate collections. Delete the collection (right-click → Delete) and re-fork from the public workspace. Postman's fork is idempotent — you'll lose any local request edits but environments are preserved.

What Postman cannot do for you

• Postman cannot replace an AI client. It's a manual exerciser — clicking Run is up to you. For autonomous AI workflows (e.g. "summarize this week's changes"), use Cursor / Claude Desktop / Claude.ai with the proper MCP install.

• Postman cannot mint a long-lived gateway PAT for you. Use the Access Tokens UI in app.rockhopper.co for that. OAuth sessions minted by web AI clients are short-lived (~30 min) and rotated server-side.

• Postman cannot bypass workspace permissions. Whatever you can see in the Rockhopper app is exactly what the MCP surface returns — same RBAC, same audit trail.

Getting help

Email [email protected] with:

1. Postman Desktop version (Help → About).

2. Which variant is failing (Remote or Local).

3. The environment you're using.

4. The full response, including status code and any error text Postman shows in the Console tab.