Provides a companion Gud API extension that reads the collection files written by the server, making them clickable in the editor sidebar.
Click on "Install 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.
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
Proprietary — see the LICENSE file. Free to install and use; redistribution and modification are restricted.
Create a new collection in the project (.gud-api/collections). Returns its id.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| variables | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the core action and return, omitting details about side effects (e.g., whether existing collections are affected), authorization needs, or behavior on duplicate names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information. Every word is meaningful with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters and no output schema, the description is too minimal. It fails to explain the variables parameter, any default behaviors, or potential errors. Given the absence of annotations and schema descriptions, more detail is needed for complete decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% documentation coverage, and the description adds no explanation of the 'name' or 'variables' parameters beyond listing them. It does not clarify the purpose of variables, constraints on names, or how the parameters should be used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new collection') and the resource ('in the project (.gud-api/collections)'), and indicates the return value ('Returns its id'). It is specific enough to distinguish from sibling tools like list_collections or get_collection, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are prerequisites or context mentioned. The description lacks any 'when-to-use' or 'when-not-to-use' cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a saved request from a collection by id or name.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | Request id or name. | |
| collection | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose the permanence of deletion, side effects (e.g., impact on other collections or requests), required permissions, or error handling. For a destructive operation, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words. Every part is functional and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and only partial parameter documentation, the description is insufficient for an agent to understand the full behavior (e.g., return value, id format, case sensitivity). It relies on assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal value beyond the schema: it confirms 'request' can be an id or name, and 'collection' is the container. However, the schema already describes 'request' (50% coverage), and the collection parameter lacks description both in schema and text. The description does not compensate fully for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete', the resource 'saved request', the context 'from a collection', and the method 'by id or name'. This distinguishes it from sibling tools like 'create_collection' or 'send_request'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., when to delete by id vs name, or when not to delete). The description is purely declarative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the active environment's variables. Secret-looking values (token/key/secret/password/…) are masked — send_request still resolves the real values server-side.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description effectively discloses the masking behavior for secret-like values and that send_request resolves them server-side, covering key behavioral traits beyond the basic read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, no redundant information. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description sufficiently explains what is returned and a critical behavior. Could mention activation context, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline 4 applies. The description adds value by explaining what is returned and a behavioral note, not needing to elaborate on schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns active environment variables and explains secret masking, a specific verb+resource with a useful detail that distinguishes it from siblings like upsert_environment or send_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this versus alternatives, but the purpose is clear enough for a simple getter. The context and sibling list provide implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full contents of one collection: folders, requests (with method/url/headers/body), and variables. Example response bodies are summarized.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection id or name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes what is returned but does not disclose any behavioral traits such as safety, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the key action without wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool returning complex nested data, the description lacks details on response structure, format, or any limitations. Mentioning that example response bodies are summarized is vague and insufficient without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema's parameter description of 'Collection id or name.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves full collection contents including folders, requests with details, and variables. It distinguishes from siblings like list_collections (presumably listing only names) and get_active_environment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when full collection data is needed, but lacks explicit guidance on when to prefer this over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Gud API collections in the project's .gud-api folder, with request counts and folder names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses the returned data (request counts, folder names) but lacks information on side effects, permissions, or error conditions. For a read-only list, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 14 words, directly states purpose and output. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with no output schema; description covers what it lists. Could be improved by describing return format or ordering, but sufficient for a basic list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4 per rubric. The description adds context about output (request counts, folder names) beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists collections with request counts and folder names, using a specific verb and resource. It distinguishes from sibling tools like create_collection or get_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or alternatives mentioned. The purpose implies use for overview, but no exclusions or comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| request | No | Inline request definition (alternative to collection+requestName). | |
| collection | No | Collection name/id when sending a saved request. | |
| requestName | No | Saved request name or id within the collection. | |
| saveExample | No | When set, capture the response as an example on the saved request. Pass a string to label it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that responses are truncated, variables are resolved, and examples can be saved. It doesn't mention rate limits or error handling, but covers the core behaviors well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load key information (execute request, return details). No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested request object, multiple optional parameters) and no output schema, the description covers the main purpose but omits details on using the 'tests' field and how to construct the request object for inline sending.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context about variable resolution and example saving, but doesn't elaborate on how to choose between inline request object and collection+requestName parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a request and returns status, timing, headers, and a truncated body. It also mentions variable resolution and optional example saving, which distinguishes it from sibling tools like list_collections or upsert_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates this tool is for sending HTTP requests, but lacks explicit guidance on when to use inline requests vs saved requests, or when not to use it. No mention of alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| setActive | No | ||
| variables | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Discloses upsert behavior and side effect of setting active environment, but does not explain update semantics (e.g., replace vs. merge variables), error conditions, or return value. Lacks detail on what 'set active' actually entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise, but could benefit from bullet points or structured explanation. Still, it is efficient with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema or annotations, the description should cover more. Missing information on return value, update behavior, error scenarios, and complete parameter details. Adequate only for the most trivial use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet description only vaguely explains 'variables' with an example, missing details on the 'enabled' subfield and the required structure. 'setActive' is implied but not explicitly connected to the parameter name. Adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create or update an environment' with examples, and implies upsert behavior via 'Matched by name'. However, lacks explicit differentiation from sibling tools like get_active_environment, which reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Mentions optional activation for send_request, but does not specify scenarios where other tools (e.g., upsert_request) would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | ||
| collection | Yes | Collection name or id. Created if missing. | |
| folderPath | No | Folder path, e.g. ["Auth","JWT"]. Created as needed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: collection creation if missing and folder path creation as needed. However, it does not clarify the exact update semantics (e.g., full replacement vs. merge) or mention any destructive side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with core purpose, followed by optional feature. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with nested objects and no output schema, the description covers high-level behavior but omits upsert conflict resolution and return value details. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (some parameter descriptions exist). The description adds meaning by linking 'matched by name' to the request.name parameter and explaining folderPath as optional nesting. Nested request object details are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'create or update a request inside a collection (matched by name)', distinguishing it from siblings like create_collection (collection-only) and send_request (execution-only). It specifies the match key and optional folder nesting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for upserting requests but does not explicitly state when to use alternatives. For example, it does not mention that create_collection should be used to create a collection alone, nor does it provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.2create_collectiondelete_requestget_active_environmentget_collectionlist_collectionssend_requestupsert_environmentupsert_requestEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Git-backed platform for skills, tools, and context for AI agents
Build, deploy, and sell AI agents for local-service businesses - from your IDE.
Give your AI agents the tools to build, manage, and run automation workflows.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/gudlab/gud-api-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
