Gud API for AI agents

AI coding agents test APIs constantly — but that testing is throwaway. An agent fires a few curl commands to check an endpoint it just built, and the moment the session ends, it's gone. You re-derive every request by hand.

The Gud API MCP server (@gudlab/gud-api-mcp) changes that. When an agent builds an endpoint, it registers the request, runs it, and captures the response — as a real Gud API collection in your project's .gud-api/ folder. Open your editor and every endpoint the agent built and tested is sitting in your sidebar, ready to click and re-run. It's git-committable, so it travels with the pull request.

One line: the API client your AI agent uses.

Works with your stack

• Any MCP client drives the server: Claude Code, Cursor, Windsurf, Codex, Cline, Zed, Continue — anything that speaks the Model Context Protocol.
• Any VS Code-compatible editor reads the collections through the companion Gud API extension: Cursor, VS Code, Windsurf, VSCodium, Antigravity, Trae, and others (via Open VSX).

The two are independent: the server just writes files, so you can use it with an agent even if your editor of choice isn't the one showing the sidebar.

How it works

Any MCP agent  →  @gudlab/gud-api-mcp  →  .gud-api/collections/*.json
(Claude Code, Cursor,                    │
 Windsurf, Codex, …)                     ▼  (live)
                     Gud API extension  →  sidebar updates + Examples tab
                     (Cursor / VS Code /        │
                      Windsurf / VSCodium…)     ▼
                                     git add .gud-api/  →  reviewed in the PR

1. The agent creates requests and environments through the MCP server.
2. The server writes them to .gud-api/ in the exact format the Gud API extension reads — no conversion, no import step.
3. The extension watches that folder and updates your sidebar live as the agent works. You'll see a "workspace collection added" notice.
4. Each request the agent runs saves an example response — open the request and check the Examples tab to see exactly what the API returned.

Setup

The server runs via npx — no global install. It's the same config for every MCP client; only the file it goes in differs.

Add this block to your client's MCP config:

{
  "mcpServers": {
    "gud-api": {
      "command": "npx",
      "args": ["-y", "@gudlab/gud-api-mcp", "--project", "."]
    }
  }
}

Client	Config location
Claude Code	.mcp.json in the project root
Cursor	~/.cursor/mcp.json (or per-project .cursor/mcp.json)
Windsurf	Windsurf Settings → MCP, or its mcp_config.json
Codex	the Codex MCP config (~/.codex/…)
Cline / Zed / Continue	that tool's MCP settings block

For best results, add the bundled skill so the agent records its testing as it goes (see the server's skill/gud-api/SKILL.md).

--project . scopes all reads and writes to the current project's .gud-api/ folder. Workspace collections are never cloud-synced, so agent output stays local and reviewable.

What the agent can do

Tool	Purpose
list_collections	See existing collections, with request counts and folders
get_collection	Full contents of one collection
create_collection	Create a collection in .gud-api/collections
upsert_request	Create/update a request (matched by name), nested under a folder path
send_request	Run a request, resolve , run tests, capture an example
delete_request	Remove a saved request
upsert_environment	Create/update a named variable set (base URL, tokens)
get_active_environment	Read active variables — secret values are masked

Example session

An agent building a POST /users endpoint in your app:

1. upsert_environment { name: "Local", variables: [{ key: "base_url", value: "http://localhost:3000" }], setActive: true }
2. upsert_request {
     collection: "MyApp API", folderPath: ["Users"],
     request: {
       name: "Create user", method: "POST", url: "{{base_url}}/users",
       headers: { "Content-Type": "application/json" }, body: "{ \"email\": \"a@b.com\" }", bodyType: "json",
       tests: [{ source: "status", operator: "eq", expected: "201" }]
     }
   }
3. send_request { collection: "MyApp API", requestName: "Create user", saveExample: "201 created" }
   → 201, tests passed, example saved

You open your editor → MyApp API is in the sidebar → click Create user → the Examples tab shows the captured 201 created response → git add .gud-api/.

Privacy & safety

• send_request executes real HTTP — no more than the curl access an agent already has, but be aware of it.
• Secrets are masked from the agent. get_active_environment masks values whose keys look like secrets (token, key, secret, password, …). The agent can use a credential by referencing its variable name — the server resolves the real value when sending — without ever reading it into context.
• Cookies are per-session and in-memory — an agent never inherits your browser session cookies.
• Writes are confined to your project — collection names are slugified, so a name can't escape the .gud-api/ folder.
• Nothing is cloud-synced — agent-created collections are workspace-scoped and stay on your machine unless you deliberately re-scope them.

Why this is different

Postman is cloud-account-first and hostile to a local, file-based agent workflow. Bruno's files are agent-writable but there's no protocol, no request execution, and no response capture. Gud API is the only API client that's agent-native and editor-native at once: the agent writes files your editor picks up instantly, and you review them in the PR alongside the code.

See how it compares: vs Postman · vs Thunder Client · vs Bruno.