# MCP — Postman Workspace

[<img src="https://run.pstmn.io/button.png" alt="Run In Postman" data-size="line">](https://god.gw.postman.com/run-collection/54299481-0b80e147-9f26-4fe5-8a87-a5dcc4a993bc?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D54299481-0b80e147-9f26-4fe5-8a87-a5dcc4a993bc%26entityType%3Dcollection%26workspaceId%3Dfd36303d-a194-4e6e-978a-3b159249ec65)

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)](/it-setup/mcp-server.md).

{% hint style="info" %}
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.
{% endhint %}

## 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](/it-setup/mcp-server.md#step-2-option-a-local-install-with-npx)            |
| Have Claude.ai or ChatGPT on the web call Rockhopper                               | The [remote gateway](/it-setup/mcp-server.md#step-2-option-b-remote-install-claude-ai-chatgpt)       |
| 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](https://github.com/modelcontextprotocol/inspector) (engineer-only, internal use) |

## Collection layout

The `Rockhopper MCP Server` collection follows the [Postman peer-vendor pattern](https://www.postman.com/explore/mcp-servers) 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](/it-setup/mcp-server.md#step-1-create-a-personal-access-token-pat).
* Postman Desktop v11.x or newer ([download](https://www.postman.com/downloads/)). 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](https://www.postman.com/rockhopper-co/rockhopper-mcp-public).
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.

{% hint style="warning" %}
**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.
{% endhint %}

## 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**.

{% hint style="warning" %}
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.
{% endhint %}

5. 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.

{% hint style="info" %}
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.
{% endhint %}

## 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.

{% hint style="info" %}
**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.
{% endhint %}

### 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 <support@rockhopper.co> 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rockhopper.co/it-setup/mcp-postman-workspace.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.