A Model Context Protocol server that lets any MCP-capable AI agent — Claude Code, Cursor, Windsurf, Codex, Cline, Zed, and others — create, run, and save API requests and collections as real Gud API files your team can open in any VS Code-compatible editor.
When an agent builds an endpoint, it registers the request, runs it, and captures
the response as an example. The collection is written to your project's
.gud-api/ folder — the same files the Gud API extension
reads. Open your editor and every endpoint the agent built is in your sidebar,
ready to click and re-run. It's git-committable, so it travels with the PR.
Neither Postman nor Bruno occupies this lane: agent-written, editor-native, git-friendly, no cloud account.
- MCP clients (this server): Claude Code, Cursor, Windsurf, Codex, Cline, Zed, Continue — any tool that speaks the Model Context Protocol.
- Editors (the companion Gud API extension that reads the files): VS Code, plus any VS Code-compatible editor that installs from Open VSX — Cursor, Windsurf, VSCodium, Antigravity, Trae, and more.
The server itself is editor-agnostic — it just writes files. You don't need the extension to use it, but the extension is what makes the collections clickable.
The server runs via npx — no global install needed. It's the same config for
every MCP client; only the file it lives in differs.
Add this to your client's MCP config (.mcp.json for Claude Code, ~/.cursor/mcp.json
for Cursor, the Windsurf/Codex/Cline equivalent, etc.):
{
"mcpServers": {
"gud-api": {
"command": "npx",
"args": ["-y", "@gudlab/gud-api-mcp", "--project", "."]
}
}
}--project . scopes all reads/writes to the current project's .gud-api/
folder. Pass an absolute path to target a different project.
| Tool | Purpose |
|---|---|
list_collections |
List collections with request counts and folders |
get_collection |
Full contents of one collection (bodies + example summaries) |
create_collection |
Create a collection in .gud-api/collections |
upsert_request |
Create/update a request (matched by name), nest under a folder path |
send_request |
Execute a request, resolve {{variables}}, run tests, optionally capture an example |
delete_request |
Remove a saved request |
upsert_environment |
Create/update a named variable set (base_url, tokens), optionally set active |
get_active_environment |
Read active variables — secret-looking values are masked |
Files are written byte-compatible with the extension (v0.5.7+): slug filenames
(payments-api.json), canonical key order, schemaVersion, trailing newline.
The MCP server targets workspace scope — files live in your project and are
never cloud-synced, so agent output stays local and reviewable.
Captured responses are stored as examples[] on each request (max 5). The
extension renders these read-only so you can see exactly what the API returned
when the agent tested it.
send_requestexecutes arbitrary HTTP — no more than thecurlaccess an agent already has, but be aware of it.- Secret masking:
get_active_environmentmasks values whose keys look like secrets (token,key,secret,password, …).send_requeststill resolves the real values server-side, so the agent can use a credential without reading it into its context. This is heuristic, not a guarantee — don't put production credentials in an agent-visible environment. - Cookies are in-memory per session — an agent never inherits your browser session cookies.
- Writes are confined to
--project— collection/environment names are slugified, so a name can't traverse out of the.gud-api/folder.
- Docs: https://gudapi-docs.gudlab.org/guide/ai-agents
- Gud API extension: VS Code Marketplace · Open VSX
- Issues: https://github.com/gudlab/gud-api/issues
Proprietary — see the LICENSE file. Free to install and use; redistribution and modification are restricted.