Gud API MCP Server lets AI agents create, run, and save API requests and collections as local, editor-compatible Gud API files.
List and inspect collections: list_collections shows collections with request counts and folders; get_collection returns full request details and variable summaries.
Create collections: create_collection adds a new collection in .gud-api/collections with optional variables.
Upsert requests: upsert_request creates or updates requests by name, nested under folders, with methods, URLs, headers, bodies, auth, body types, and tests.
Send requests: send_request executes saved or inline requests, resolves {{variables}}, runs assertions, and optionally captures the response as an example.
Delete requests: delete_request removes saved requests from a collection.
Manage environments: upsert_environment creates/updates named variable sets and can set the active environment; get_active_environment reads active variables with secret-like values masked.
Works with any MCP client and local files: runs via npx, writes git-committable .gud-api/ files compatible with the Gud API VS Code extension, with writes scoped to the project folder{
Provides a companion Gud API extension that reads the collection files written by the server, making them clickable in the editor sidebar.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gud API MCP Server Add a GET request to /users and save the response as an example."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
This repository is the public source for the MCP server. The Gud API editor
extension UI is proprietary. Report extension bugs at
gudlab/gud-api. Keep using
npx @gudlab/gud-api-mcp — this package stays public.
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.
Related MCP server: RequestBin MCP Server
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 with request counts and folders |
| Full contents of one collection (bodies + example summaries) |
| Create a collection in |
| Create/update a request (matched by name), nest under a folder path |
| Execute a request, resolve |
| Remove a saved request |
| Create/update a named variable set (base_url, tokens), optionally set active |
| 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_request executes arbitrary HTTP — no more than the curl access an
agent already has, but be aware of it.
Secret masking: get_active_environment masks values whose keys look like
secrets (token, key, secret, password, …). send_request still 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.
Gud API extension: VS Code Marketplace · Open VSX
Extension issues (proprietary UI): https://github.com/gudlab/gud-api/issues
This server's source: https://github.com/gudlab/gud-api-mcp
Proprietary — see the LICENSE file. Free to install and use; redistribution and modification are restricted. The editor UI is closed; this MCP package remains public on npm and GitHub.
Create a new collection in the project (.gud-api/collections). Returns its id.
Inputs: name (required), variables.
Delete a saved request from a collection by id or name.
Inputs: request (required), collection (required).
Return the active environment's variables. Secret-looking values (token/key/secret/password/…) are masked — send_request still resolves the real values server-side.
Inputs: no named parameters.
Get the full contents of one collection: folders, requests (with method/url/headers/body), and variables. Example response bodies are summarized.
Inputs: collection (required).
List all Gud API collections in the project's .gud-api folder, with request counts and folder names.
Inputs: no named parameters.
Execute a request and return status, timing, headers, and a (truncated) body. Resolves {{variables}} from the active environment and the request's collection. Optionally capture the response as a saved example.
Inputs: request, collection, requestName, saveExample.
Create or update an environment (a named set of variables, e.g. base_url and tokens). Matched by name. Optionally set it active for subsequent send_request calls.
Inputs: name (required), variables (required), setActive.
Create or update a request inside a collection (matched by name). The collection is created if it doesn't exist. Optionally nest it under a folder path.
Inputs: request (required), collection (required), folderPath.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Each tool has a clear and distinct purpose: creating vs listing collections, deleting requests, managing environments, executing requests. No overlap in functionality.
All tools follow a consistent verb_noun pattern (e.g., create_collection, list_collections, send_request). Naming is uniform with underscores and clear verbs.
8 tools is well-scoped for an API client server, covering collection management, request management, environment handling, and request execution without being bloated.
Core workflows are covered, but there are minor gaps: no delete_collection or update_collection (though update is handled via upsert_request on requests), and no list_environments or delete_environment.
Give your AI agents trusted access to the full Postman platform.
Git-backed platform for skills, tools, and context for AI agents
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Build, deploy, and sell AI agents for local-service businesses - from your IDE.
