DocsAI Agents

MCP Server

Connect Better Fullstack to Claude Code, Cursor, Codex, VS Code, and other MCP clients, and call its tools safely.

The mcp command starts the Better Fullstack MCP server over stdio. Agents use it to discover stacks, inspect schemas, validate compatibility, preview generated files, create projects, and evolve existing ones through structured tool calls instead of guessing CLI flags.

Install the server and both Better Fullstack skills for every supported agent detected on your machine:

bash

npx create-better-fullstack@latest install

See install for target detection, dry runs, JSON receipts, and uninstall. The launcher commands below start the server directly and remain useful for manual setup.

npx -y create-better-fullstack@latest mcp

Manual setup

$ claude mcp add --scope user better-fullstack -- npx -y create-better-fullstack@latest mcp

run in your terminal

One-line commands for agents reading this as Markdown:

bash

claude mcp add --scope user better-fullstack -- npx -y create-better-fullstack@latest mcp
codex mcp add better-fullstack -- npx -y create-better-fullstack@latest mcp
gemini mcp add --scope user better-fullstack npx -y create-better-fullstack@latest mcp
kimi mcp add better-fullstack -- npx -y create-better-fullstack@latest mcp
code --add-mcp '{"name":"better-fullstack","command":"npx","args":["-y","create-better-fullstack@latest","mcp"]}'

Cursor, Windsurf, Claude Desktop, and other clients using mcpServers take the same stdio server:

json

{
  "mcpServers": {
    "better-fullstack": {
      "command": "npx",
      "args": ["-y", "create-better-fullstack@latest", "mcp"]
    }
  }
}

Cursor's global file is ~/.cursor/mcp.json; Windsurf uses ~/.codeium/windsurf/mcp_config.json. OpenCode's global ~/.config/opencode/opencode.json uses a different shape:

json

{
  "mcp": {
    "better-fullstack": {
      "type": "local",
      "command": ["npx", "-y", "create-better-fullstack@latest", "mcp"],
      "enabled": true
    }
  }
}

Zed uses context_servers in ~/.zed/settings.json on macOS and ~/.config/zed/settings.json on Linux:

json

{
  "context_servers": {
    "better-fullstack": {
      "command": "npx",
      "args": ["-y", "create-better-fullstack@latest", "mcp"]
    }
  }
}

VS Code uses servers; Kilo Code follows OpenCode's mcp shape. Swap the launcher per package manager:

Package manager	`command`	`args`
npm	`npx`	`["-y", "create-better-fullstack@latest", "mcp"]`
pnpm	`pnpm`	`["dlx", "create-better-fullstack@latest", "mcp"]`
Bun	`bunx`	`["create-better-fullstack@latest", "mcp"]`
Yarn	`yarn`	`["dlx", "create-better-fullstack@latest", "mcp"]`

Codex also accepts a TOML entry in ~/.codex/config.toml:

toml

[mcp_servers.better-fullstack]
command = "npx"
args = ["-y", "create-better-fullstack@latest", "mcp"]

The automatic installer copies two skills alongside the MCP connection. The agent plugin remains available for plugin marketplaces, and the agent skill documents the CLI-only path.

Resources

Resource	Contents
`docs://compatibility-rules`	Compatibility rules for stack combinations.
`docs://stack-options`	Available technology options by category.
`docs://getting-started`	Quick-start recipes for supported ecosystems.
`docs://capability-evidence-levels`	Per-option evidence, freshness, ownership, recipes, and limits.

Tools

Call the live guidance and schema tools instead of trusting prose; the schema is the authoritative contract.

Discovery and validation (read-only)

Tool	Purpose
`bfs_get_guidance`	Current workflow rules, field semantics, and constraints. Call it first.
`bfs_get_schema`	Valid options for one category or all, optionally scoped to an ecosystem.
`bfs_list_presets`	Ready-made stack presets with IDs and summaries.
`bfs_list_starter_tracks`	Canonical editable tracks with exact Stack Parts, filters, and evidence.
`bfs_recommend_stack`	Deterministic recommendation from a natural-language brief.
`bfs_check_compatibility`	Adjusted selections, changes, and remaining issues for a proposed stack.
`bfs_get_capability_evidence`	Receipt-backed evidence, maturity, freshness, owners, and limitations.
`bfs_get_project_context`	Bounded project roles, evidence, versions, recipes, and safe actions.

New projects

Tool	Purpose
`bfs_plan_project`	Generates the project in memory and returns the file summary. Never writes.
`bfs_create_project`	Writes files and `bts.jsonc` with manifest-v2 provenance. No install, no Git.

Existing-project lifecycle

Tool	Purpose
`bfs_get_project_status`	Read-only recognition, dependency/env diagnostics, provenance, upgrade summary.
`bfs_check_project`	Executes every generated target; build tools may write locks, caches, or artifacts.
`bfs_plan_doctor_fix`	Plans canonical graph/config drift repair and returns a current-state review token.
`bfs_apply_doctor_fix`	Applies the unchanged config repair in one recoverable transaction.
`bfs_plan_project_adoption`	Infers likely Stack Parts and uncertainty without writing a baseline.
`bfs_confirm_project_adoption`	Creates an unverified baseline only with the exact current-state token.
`bfs_plan_project_update`	Categorizes current-template drift and returns a bounded review token when eligible.
`bfs_apply_project_update`	Applies token-bound files transactionally with provenance-aware safeguards.
`bfs_list_project_recovery_points`	Lists recovery IDs, lifecycle status, integrity, and current restore safety.
`bfs_get_project_recovery_point`	Shows and validates one recovery point without writing.
`bfs_verify_project_recovery_point`	Rechecks one recovery point against its backups and current project state.
`bfs_prune_project_recovery_points`	Previews retention and returns a token; apply deletes only the reviewed eligible terminal points.
`bfs_recover_project_transaction`	Restores every bound path of a transaction exactly once.
`bfs_plan_part_removal`	Plans exact non-primary capability removal and returns a review token.
`bfs_apply_part_removal`	Applies a reviewed removal in a recoverable transaction.
`bfs_plan_primary_role_replacement`	Plans exact Primary Role replacement, owner rewiring, and migration boundaries.
`bfs_apply_primary_role_replacement`	Applies the reviewed replacement with its token and architecture acknowledgement.
`bfs_plan_stack_update`	Plans broad stack changes against `bts.jsonc`.
`bfs_apply_stack_update`	Applies a reviewed stack update, preserving user-edited generated files.
`bfs_plan_addition`	Plans focused Stack Part or deploy additions.
`bfs_add_feature`	Applies focused Stack Part or deploy additions after review.
`bfs_plan_gen`	Plans an in-project resource or route with exact file bodies and preimage hashes.
`bfs_apply_gen`	Applies the unchanged generation token in one recovery transaction.
`bfs_check_recipes`	Validates recipe-owned files and managed entries without executing code.
`bfs_get_recipe_history`	Correlates local recipe records with recovery transactions.
`bfs_plan_registry_add`	Plans a local capability pack, including files, dependencies, and metadata merges.
`bfs_apply_registry_add`	Applies the unchanged local-pack token without running a package manager.

Planning, creation, and addition responses include graph metadata (graphSummary, effectiveStack, stackPartSpecs) alongside the generated file or mutation summary.

Recommended workflows

Discover a stack. Call guidance first, then presets or a schema lookup, then validate with the compatibility tool.

Create a project. Plan in memory, show the plan to the user, then create with the same stack fields after approval. Report the returned install command because write tools never install dependencies.

Update an existing stack. Plan with an absolute project directory and the scaffold-time fields to change, review adjustments and blockers, then apply the same fields. Set acknowledgeArchitectureChange only after the user accepts listed data/schema risks.

Repair config drift. Call bfs_plan_doctor_fix, show every changed field and reason, then pass the exact unchanged reviewToken to bfs_apply_doctor_fix. A stale token fails before the bts.jsonc write. Keep the returned recovery ID until project checks pass.

Replace a Primary Role. Call bfs_plan_primary_role_replacement with one exact selected frontend, backend, mobile, or database part and a same-role replacement. Show owner rewiring, migration steps, and application-data boundaries. Call the apply tool only with the unchanged token and the required architecture acknowledgement. Cross-ecosystem owner capabilities need a separate reviewed removal or replacement.

Adopt an older project. When status reports a missing manifest, call bfs_plan_project_adoption. Show the likely Stack Parts, confidence, template evidence, and uncertainty to the user. Call bfs_confirm_project_adoption only after approval and only with the unchanged token. The result remains unverified lineage.

Refresh templates. Read status, run the executable check when truthful verification is wanted, plan the update, review the hash-bound categories, then apply the exact unchanged token. Structured merge content is exact up to 32 KiB per file; oversized reviews return metadata and no token. Keep the returned recovery ID until checks pass, and recover with the transaction ID if anything goes wrong.

Manage recovery points. List first when the transaction ID is unknown. Show or verify the selected point before restore. Prune with apply: false first, then pass its unchanged reviewToken with apply: true. Pending and invalid points are always retained, and keep protects the newest valid points.

Generate a persistent recipe. Call bfs_plan_gen, review every exact file and shared-region change, then call bfs_apply_gen with its unchanged token. Run the returned migration and integration commands. Use bfs_check_recipes for ownership integrity and bfs_get_recipe_history to find the recovery transaction. bfs_get_project_context returns the same bounded context document as CLI JSON and does not include source code. Its commands use a relative project path when possible, or an absolute path when that is required to target the inspected project.

Troubleshooting client response parsing

If a JavaScript MCP client reports TypeError: schema.safeParse is not a function, check the arguments passed to client.callTool. In @modelcontextprotocol/sdk v1, the second argument is a result schema. Request options belong in the third argument:

// @modelcontextprotocol/sdk v1
const result = await client.callTool(request, undefined, { timeout: 120_000 });

The split @modelcontextprotocol/client v2 package takes options as the second argument:

// @modelcontextprotocol/client v2
const result = await client.callTool(request, { timeout: 120_000 });

Passing the v2 argument layout to v1 can fail while parsing a successful response. Check whether the project directory and bts.jsonc already exist before retrying create. If they do, inspect the project with bfs_get_project_status.

Call client.listTools() before invoking tools so the client can validate structured responses against their advertised output schemas.

Rules for agents

Start with guidance; get exact field names, value sets, and array shapes from the live schema.
Set ecosystem first, keep the field family aligned with it, preserve arrays as arrays, and use none only where the schema allows it.
Apply exactly what was planned. If the request changes, plan again.
Never call a write tool before its corresponding plan is reviewed by the user.
Surface compatibility adjustments and manual-review blockers instead of silently accepting them.
Missing, stale, modified, cross-project, or oversized tokens fail closed. Migrated or manually adopted manifests additionally require acknowledgeUnprovenManifestV1: true.
Architecture-changing updates never migrate application data or schemas automatically.
After every write, report the returned install command plus relevant test and run commands.

Agent prompt

text

Use Better Fullstack MCP. Call bfs_get_guidance first, then discover the
stack with presets, a recommendation, or bfs_get_schema. Validate it with
bfs_check_compatibility and preview it with bfs_plan_project. Only call
bfs_create_project after I approve the plan. For an existing project's
stack, use bfs_plan_stack_update before bfs_apply_stack_update. Tell me
the returned install, test, and run commands because write tools do not
install dependencies. For current-template drift, call bfs_get_project_status,
bfs_check_project, and bfs_plan_project_update; only pass its exact reviewToken
to bfs_apply_project_update after I approve. Keep the returned recovery
transaction ID until checks pass. Use bfs_plan_doctor_fix before
bfs_apply_doctor_fix for graph/config drift. Use
bfs_plan_primary_role_replacement before bfs_apply_primary_role_replacement
for frontend, backend, mobile, or database replacement.