---
title: MCP Server
description: Connect Better Fullstack to Claude Code, Cursor, Codex, VS Code, and other MCP clients, and call its tools safely.
translationStatus: pending
updated: 2026-09-05
---

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`](/docs/cli/install/) for target detection, dry runs, JSON receipts, and uninstall.
The launcher commands below start the server directly and remain useful for manual setup.

<PMTabs
  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"
/>

<Callout kind="info" title="Protocol compatibility is automatic">
The server negotiates both the 2025 MCP protocol family and MCP 2026-07-28 without client-specific flags. Modern clients get the stateless-core request model with cache hints; older clients continue through legacy initialization.
</Callout>

## Manual setup

<McpClientTabs />

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](/docs/ai/overview/#agent-plugin) remains available for plugin marketplaces, and the
[agent skill](/docs/ai/overview/#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:

```ts
// @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:

```ts
// @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.
```