freebuff-mcp-server
Run and manage Freebuff coding-agent sessions from any MCP client (VS Code, etc.) via MCP tools and resources.
freebuff_run: run the agent on a prompt; default agent is read-only (freebuff-ask) for safe codebase Q&A, or passagent: 'codebuff/base@0.0.16'to allow file edits and terminal commands. Supportscwd,session_idfor continuations,max_steps,timeout_seconds,cost_mode(includingfree), andforce_resume.freebuff_status: check authentication, backend connectivity, and storage info.freebuff_stop: cancel an in-flight agent run.freebuff_delete: delete a session by id from memory and disk.freebuff_sessions: list sessions (memory + disk) with token-size estimates.MCP resources: browse a JSON session index (
freebuff://sessions) and read markdown transcripts (freebuff://sessions/{id}/transcript).Sessions persist across server restarts (default
~/.freebuff-mcp/sessions/, configurable viaFREEBUFF_MCP_DIR), with pruning viaFREEBUFF_MCP_MAX_SESSIONSandFREEBUFF_MCP_MAX_AGE_DAYS.Resume guard: warns above
FREEBUFF_MCP_RESUME_WARN_TOKENS(default 80000) and refuses resumption aboveFREEBUFF_MCP_RESUME_MAX_TOKENS(default 150000) unlessforce_resume: true.
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., "@freebuff-mcp-server why does this test fail in src/app.test.ts?"
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.
freebuff-mcp-server
Run the Freebuff coding agent from inside VS Code (or any MCP client) via the Model Context Protocol. Delegate coding tasks to the agent without leaving the editor.
Tools
Tool | What it does |
| Run the agent on a prompt. Sessions are continuable via |
| Check auth + backend connectivity + storage info. |
| Cancel the in-flight run. |
| Delete a session by id (memory + disk). |
| List sessions (memory + disk) with token-size estimates. |
freebuff_run options: prompt (required), cwd, agent, session_id,
max_steps, timeout_seconds, cost_mode (free ≈ the CLI's --lite
mode), force_resume.
Safe-by-default: read-only ask agent
By default freebuff_run uses a built-in local agent, freebuff-ask
(read-only): it can read_files, list_directory, glob, and code_search,
but has no write or terminal tools, so it can't modify your workspace.
Ideal for codebase Q&A like "where is the auth middleware?" or "why does this
test fail?".
codebuff/askis not published to the public agent registry, so this server ships its own equivalent definition (z-ai/glm-4.6).
To let the agent edit files and run commands, pass
agent: 'codebuff/base@0.0.16' explicitly.
Related MCP server: BlackHole
MCP resources
URI | What it is |
| JSON index of all sessions. |
| Markdown transcript (user/assistant/tool messages). |
Transcripts appear in resources/list, so MCP clients can browse past runs.
Session persistence & resume guard
Sessions are written to disk after every run and survive server restarts:
Default location:
~/.freebuff-mcp/sessions/<id>.jsonOverride with
FREEBUFF_MCP_DIR(directory) — the test suite uses thisPruning: keep at most
FREEBUFF_MCP_MAX_SESSIONS(default 50), delete older thanFREEBUFF_MCP_MAX_AGE_DAYS(default 30); runs on every saveRestarts: pass a previous
session_idtofreebuff_runin a brand-new server process — it loads from disk and continues the conversation
Because agent context windows are finite, resuming is guarded by a character-based token estimate (~4 chars/token, an upper bound — the backend still does its own truncation/compaction):
Env var | Default | Behavior |
| 80000 | Warn when resuming above this size |
| 150000 | Refuse to resume above this unless |
Estimates are stored with each session and shown by freebuff_sessions
(~12345 tokens), so oversized sessions are visible before you try.
Installation
Published as freebuff-mcp-server.
Use it directly with npx (no clone needed):
npx -y freebuff-mcp-serverOr install globally:
npm install -g freebuff-mcp-server
freebuff-mcp-serverLatest release · all releases · release notes
Verifying the published package
Releases are published from GitHub Actions, so the registry records a provenance attestation tying the tarball to this repository, the commit it was built from, and the workflow run that published it. To check an install:
npm audit signatures # verifies registry signatures and provenanceThe raw attestation bundle for a version is served by the registry:
https://registry.npmjs.org/-/npm/v1/attestations/freebuff-mcp-server@<version>For example:
0.3.1.
npm also surfaces provenance on the
package page.
Authentication
Get an API key at https://www.codebuff.com/api-keys (same account as your Freebuff login), then supply it in one of these ways (first match wins):
--api-key <key>argumentFREEBUFF_API_KEYorCODEBUFF_API_KEYenvironment variableYour existing Freebuff CLI login (
~/.config/manicode/credentials.json) — tried automatically as a fallback
Note (verified experimentally, Sept 2026): the stored CLI session token authenticates and reaches the backend, but SDK runs are billed through the Codebuff API-key path, so it currently yields
Payment Required(normal mode) orForbidden(cost_mode: "free"). Generate an API key at the link above and the server works out of the box. If your account has no SDK access, that's an account/billing matter on codebuff.com — there is no free headless path in the Freebuff CLI itself today.
Use in VS Code
A ready-made config is included at .vscode/mcp.json (workspace root). It
launches the server via npx and prompts for your API key on first use:
{
"servers": {
"freebuff": {
"type": "stdio",
"command": "npx",
"args": ["-y", "freebuff-mcp-server"],
"env": { "CODEBUFF_API_KEY": "${input:codebuffApiKey}" }
}
}
}For any other MCP client, the launch command is the same:
npx -y freebuff-mcp-server.
Publishing (maintainers)
Publishing is automated from GitHub releases:
Authenticate publishing — either works, and npm tries OIDC first:
npm trusted publishing (preferred, no secret): on npmjs.com add a trusted publisher for this repo (
publish.ymlworkflow) under the package's Settings → Trusted publishing. Requires npm CLI ≥ 11.5.1 and Node ≥ 22.14, which the workflow provides by running Node 24.NPM_TOKENfallback: add an npm automation/granular token as a repository secret (needed for the very first publish, before the package exists on npm and a trusted publisher can be configured)
Bump
package.jsonversion, commit, and tag itCreate a GitHub release with tag
v<version>(e.g.v0.3.1)
The publish.yml workflow then typechecks, builds, runs the protocol-only
smoke test, verifies the tag matches the package version, reports which
credential path is in use, and runs npm publish --provenance --access public.
Re-running a stuck publish does not need a new release: dispatch the workflow
against the release tag (gh workflow run publish.yml --ref v<version>).
Once the package exists on npm the recommended route is staged publishing, which parks the version in a staging area until a maintainer approves it with 2FA, so no long-lived token is needed at all:
gh workflow run publish.yml --ref v<version> -f staging=true
npm stage list && npm stage approve <stage-id>See docs/publishing.md for the full evaluation, the requirements, and the rollout order.
Manual publish still works: npm publish (prepublishOnly re-runs typecheck +
build). The tarball contains only dist/ + README.md (~12 kB packed).
CI
.github/workflows/ci.yml runs on every push/PR touching src/, test/
(Node 20 + 22): npm run audit:runtime (fails on runtime-scope advisories)
→ typecheck → build → npm test with SMOKE_SKIP_NETWORK=1 → npm run test:contract.
That mode exercises the full MCP protocol surface (handshake, tool schemas,
resource listing/reads, delete and resume error paths, persistence across a
restart) without agent runs, since CI has no credentials. The full test with
real agent runs still works locally: npm test.
Development
npm install
npm run typecheck # tsc --noEmit
npm run build # emit dist/index.js
npm run audit:runtime # fail on runtime-scope advisories (AUDIT_MIN_SEVERITY=high to raise the bar)
npm run test:contract # verify tools/resources against test/contract.snapshot.json
# (--update to accept an intentional surface change)
node test/smoke.js # full end-to-end test (see below)
# optional args: [agentId] [costMode]The smoke test exercises: initialize → tools/list → status → two real agent
runs → sessions list (with token estimates) → resources/list +
resources/read (index + transcript) → freebuff_delete (unknown id, real
delete, transcript gone) → restart: a second server instance must list the
surviving session, serve its transcript from disk, refuse an oversized resume
(FREEBUFF_MCP_RESUME_MAX_TOKENS=1), resume with force_resume, and still
reject unknown ids.
stdout is reserved for the MCP protocol; all diagnostics go to stderr.
Status & limitations
The MCP layer (tools, resources, persistence, resume guard, cancellation, timeouts) is complete and tested against a live server.
Runs require a Codebuff API key with SDK access (see Authentication).
Transcripts omit
systemmessages and reasoning parts.Token estimates are character-based upper bounds, not exact counts.
undiciand@ai-sdk/provider-utilsare pinned to patched versions via npmoverridesinpackage.json(transitive deps of@codebuff/sdk); revisit these pins when the SDK ships a dependency refresh.
Available Tools
5 toolsfreebuff_deleteA
Delete a Freebuff agent session by id — from memory and disk.
Returns error if the id is unknown. The transcript resource for a deleted session disappears; active runs must be cancelled (freebuff_stop) before deleting their session.
Inputs: session_id (required).
freebuff_runA
Run the Freebuff coding agent on a prompt, inside a workspace folder.
By default runs the built-in read-only 'freebuff-ask' agent, which can read files, search code, and answer questions but cannot modify anything — safe for codebase Q&A. Pass agent: 'codebuff/base@0.0.16' to let the agent edit files and run commands.
Returns the agent's final answer plus a log of what it did. Continue a conversation by passing the session_id returned from a previous run (sessions persist across server restarts).
Inputs: prompt (required), cwd, agent, cost_mode, +4 more.
freebuff_sessionsA
List Freebuff agent sessions known to this server (memory + persisted on disk).
Inputs: no named parameters.
freebuff_statusA
Check whether the Freebuff MCP server has valid credentials and can reach the agent backend.
Inputs: no named parameters.
freebuff_stopA
Cancel the currently running Freebuff agent session, if any.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: run executes the agent, stop cancels a run, status checks connectivity, sessions lists stored sessions, and delete removes a session. There is no meaningful overlap or ambiguity between them.
All tools use the freebuff_ prefix and snake_case, and most are verb-based (run, stop, delete, status). The exception is freebuff_sessions, which is a noun rather than an action verb, but it is still predictable and easily understood.
Five tools is well-scoped for the server's purpose: managing and interacting with Freebuff coding agent sessions. Each tool covers a necessary part of the lifecycle without redundancy or bloat.
The tool surface covers the full session lifecycle: create/continue with run, cancel with stop, list with sessions, delete with delete, and validate availability with status. There are no obvious dead ends for the stated domain.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables approved Microsoft 365 agents to be queried from VS Code and MCP-compatible AI clients through a local MCP bridge.1MIT
- AlicenseNot gradedqualityCmaintenanceBridges web-based AI agents to a local VS Code workspace over MCP Streamable HTTP, letting them inspect files, edit code, and run persistent shell commands within session-scoped boundaries. Risky, destructive, or out-of-scope operations pause for explicit human approval, with session state surviving reconnects.8 npmGPL 3.0
- AlicenseNot gradedqualityBmaintenanceExposes a running VS Code instance to AI agents via MCP, enabling file operations, LSP diagnostics, terminal commands, Git workflows, and refactoring.23MIT
- AlicenseNot gradedqualityAmaintenanceEnables any MCP-compatible client to run reusable, Markdown-defined coding agents (such as code reviewers, test writers, or investigators) through a chosen coding CLI backend. Supports shared backend and model configuration across clients, permission levels, and session continuation for longer tasks.161 npmMIT