Use HITOP with Claude Code and Cursor

Connect hitop to Claude Code, Cursor or any MCP client with hitop mcp: list, read, run, create and update the requests of a collection folder, with secrets masked.

What hitop mcp does

hitop mcp is a Model Context Protocol server. An AI coding tool starts it, talks to it over stdin and stdout, and can then work with your API collection the way you do in the terminal:

hitop mcp ./my-api

The argument is a collection folder (the hitop.yaml, requests/ and environments/ layout from hitop init). Leave it out to serve the collections in hitop's global storage instead, the ones hitop collections list shows.

Check that your hitop has it with hitop mcp --help; update with cargo install hitop or a binary from GitHub Releases.

Requests run through the same code as hitop run: the same variables, scripts, assertions and cookie jar. The server runs on your machine and sends nothing but your requests (plus the weekly usage ping, if you turned it on).

The tools

Tool	What it does
`list_collections`	The folder's collection, or every collection in global storage.
`list_requests`	A collection's requests in run order: name, method, URL, file.
`get_request`	One request as saved: method, URL, headers, body, auth and scripts.
`run_request`	Sends one request and returns status, headers, body (cut at 64 KiB), timing and assertion results.
`run_collection`	Runs every request in order and returns the run report (`reportVersion` 1), like `hitop run --reporter json`.
`create_request`	Adds a request; in a folder it becomes a new YAML file under `requests/`.
`update_request`	Changes the fields you give of a saved request.
`list_environments`	Environments and globals with their variables; secret variables by name only.
`set_environment`	Picks the environment that later runs use, for this session only.
`run_websocket`	Opens a saved WebSocket request (or a `ws://`/`wss://` URL, sent without the collection's auth), sends its saved messages by name and any texts, collects what the server sends until `count` messages or `wait_ms`, then closes. At most 100 messages, 256 KiB and 60 s; nothing stays open between calls.
`import_openapi`	Imports an OpenAPI 3.0 or 3.1 spec (a URL, or a file inside the workspace) as a new collection folder inside the workspace (`to`), or into global storage.
`sync_openapi`	Brings a collection imported from a spec up to a newer one. Returns the diff (operations added, changed, removed; header and query rows one by one) without writing; `apply: true` writes it, keeping your edits.

The WebSocket and OpenAPI tools need hitop 1.1 or later.

There is no delete tool: removing requests stays with you (hitop requests delete, or git rm in a folder). The one exception is sync_openapi called with both apply and prune, which deletes the requests of operations the spec dropped. In a folder every change the assistant makes is an ordinary file change, so git diff shows it and git checkout undoes it.

File paths the tools take (a spec file, the to folder) must be inside the workspace: the served folder, or with global storage the directory the client starts hitop mcp in. Anything outside, or with .., is refused.

Claude Code

Add a .mcp.json file to the root of your project:

{
  "mcpServers": {
    "hitop": {
      "command": "hitop",
      "args": ["mcp", "./my-api"]
    }
  }
}

Or add it from the terminal with claude mcp add hitop -- hitop mcp ./my-api. Claude Code asks once before it starts a server from a project's .mcp.json. Then ask for things like "run the orders requests against staging and tell me which assertions fail" or "add a request for DELETE /orders/{id} with a 204 check".

Cursor

Cursor reads the same mcpServers shape from .cursor/mcp.json in the project (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "hitop": {
      "command": "hitop",
      "args": ["mcp", "./my-api"]
    }
  }
}

A relative folder is resolved from the directory the client starts the server in, normally the project root. If the server can't find the folder, give an absolute path. hitop must be on the PATH the tool sees; otherwise give its full path as command.

Environments

With a folder, runs start without an environment; with global storage they start with your active environment, as hitop run does. The assistant picks one with set_environment (or gives environment to a single run). That choice lasts for the session and is not saved: your active environment in hitop stays as it is.

Variables resolve as in hitop run, later ones winning: globals, collection, environment, the call's variables, variables set by scripts, then secrets.

Secrets

The assistant never sees a secret's value:

Secret values come from the OS keychain (hitop secret set token --env staging) or from HITOP_SECRET_<ENV>_<NAME> environment variables, exactly as for hitop run. There is no prompt: stdin belongs to the protocol.
Every secret value is shown as •••• in what the tools return: URLs, response headers and bodies, assertion messages and errors.
list_environments lists secret variables by name, without values.
create_request and update_request refuse a request that contains a secret's value and ask for ${name} instead, so values never land in your collection files.

Don't put secret values in .mcp.json or .cursor/mcp.json: those files are usually committed. Keep them in the keychain, or export HITOP_SECRET_* variables in the shell the editor starts from.

A secret only stays hidden from the assistant if hitop knows it is a secret. A token typed straight into a request, or a value a response hands back that is not a secret variable, is just data and is shown.

Other clients

Any MCP client that starts stdio servers works the same way: the command is hitop and the arguments are mcp and the folder. To try the tools by hand, the MCP inspector has a command line mode:

npx @modelcontextprotocol/inspector --cli hitop mcp ./my-api --method tools/list