baton-mcp

A local stdio MCP server that gives AI agents structured access to a Baton workspace: list, read, edit, and run requests.

Baton is a git-native API client — collections, environments, and schedules are plain YAML files in a git repository you own. This server operates on a local checkout, so agent changes show up in the app instantly and go through git review like any other change.

Use it

// Claude Code: .mcp.json
{
  "mcpServers": {
    "baton": {
      "command": "npx",
      "args": ["-y", "@dudko.dev/baton-mcp", "--workspace", "/path/to/my-apis"]
    }
  }
}

| Flag | Meaning | |---|---| | --workspace <dir> | The workspace root — the folder holding baton.yaml. Defaults to the working directory. | | --allow-run | Lets the agent execute requests. Off by default. |

Requires Node.js 24 or newer.

Tools

| Tool | What it does | |---|---| | workspace_info | Collections, environments, schedules, load issues. | | list_requests | Requests with method, url, tags — optionally under one collection. | | get_request | Full parsed request, raw YAML, and where its auth comes from. | | upsert_request | Create or replace a request; writes deterministic YAML. | | move_request | Move or rename a request, keeping its id. | | delete_request | Delete a request. | | upsert_collection | Create or replace a collection, its variables, and its auth. | | list_environments | Variables and secret names. | | upsert_environment | Create or replace an environment. | | get_script / upsert_script | Read and write pre-request, test, and shared library scripts. | | run_request | Execute one request (needs --allow-run). | | run_collection | Execute every request under a collection (needs --allow-run). |

Secrets

Secret values never cross the MCP boundary. Environment files hold secret names; the values live in the OS secure store. A tool call carrying a literal credential is rejected with a message telling the agent to use a {{secret:name}} reference instead. Responses returned to agents truncate bodies and mask Authorization, Cookie, Set-Cookie, and X-API-Key.

Runs are capability-gated because an agent editing files should not silently fire live traffic; with runs disabled the tools still exist and return a clear error, so the agent can tell you how to turn them on.

The server never touches git — commits stay a deliberate action.

License

Proprietary — see LICENSE.

Free for personal, non-commercial use. Commercial use is free for small entities: your group must have raised less than USD 250,000 in total, be valued at less than USD 250,000, and have annual gross revenue under USD 1,000,000. Above any of the three, commercial use needs a license — write to [email protected].

Redistribution is not permitted. Installing from npm, caching in your own registry proxy, and building your own deployment images are (see Section 4 of the license); republishing, forking, or bundling these packages into something you ship are not.