diff --git a/docs/04-get-started/02-quickstart.md b/docs/04-get-started/02-quickstart.md index 81e63759..397877b6 100644 --- a/docs/04-get-started/02-quickstart.md +++ b/docs/04-get-started/02-quickstart.md @@ -66,7 +66,7 @@ Next, open your newly created project with your favorite AI powered editor. Open :::important -If you are using Cursor, you will need to **enable the Serverpod and Dart MCP servers** in your project settings (_Cursor Settings_ > _Tools & MCPs_). +If you are using Cursor, you will need to **enable the Serverpod and Dart MCP servers**: open **Customize** in the sidebar, click **MCPs**, and turn on both servers. ::: diff --git a/docs/06-concepts/cli/commands/mcp-server/_mcp-server.md b/docs/06-concepts/cli/commands/mcp-server/_mcp-server.md index f0e353cf..7b86c8c7 100644 --- a/docs/06-concepts/cli/commands/mcp-server/_mcp-server.md +++ b/docs/06-concepts/cli/commands/mcp-server/_mcp-server.md @@ -8,7 +8,7 @@ The bridge drives a running session, so start one with `serverpod start` before ## Set up your editor -`serverpod create` writes the MCP configuration for the editors you select, so a new project needs no manual setup. Run `serverpod create .` in an existing project to add the same files. +The `serverpod create` command writes the MCP configuration for the editors you select, so a new project needs no manual setup. Run `serverpod create .` in an existing project to add the same files. | Editor | File | | --- | --- | @@ -19,7 +19,7 @@ The bridge drives a running session, so start one with `serverpod start` before | Codex | `.codex/config.toml` | | OpenCode | `opencode.json` | -In Cursor, once the file is created, open Cursor Settings and go to **Customize > MCPs**. There, make sure both the `serverpod` and `dart` servers are enabled. +In Cursor, once the file is created, open **Customize** in the sidebar and click **MCPs**. There, make sure both the `serverpod` and `dart` servers are turned on. ### Set up any other MCP client @@ -48,8 +48,8 @@ Module projects get only the Dart MCP server. A module has no runnable server, s ## Migrations and your data -The bridge exposes three migration tools. `create_migration` and `create_repair_migration` write migration files without changing your database. Both accept a `force` parameter that proceeds past Serverpod's warning that a change may destroy data. `apply_migrations` then applies the pending migrations to your database. +The bridge exposes three migration tools. The `create_migration` and `create_repair_migration` tools write migration files without changing your database. Both accept a `force` parameter that proceeds past Serverpod's warning that a change may destroy data. The `apply_migrations` tool then applies the pending migrations to your database. :::warning -`apply_migrations` takes no parameters and applies every pending migration, including one an agent created with `force`. Keep `serverpod start` in its default `development` run mode, because another mode loads that environment's database. Review each `apply_migrations` call before you approve it. +The `apply_migrations` tool takes no parameters and applies every pending migration, including one an agent created with `force`. Keep `serverpod start` in its default `development` run mode, because another mode loads that environment's database. Review each `apply_migrations` call before you approve it. ::: diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index 14b7fc9b..eda7da8c 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -332,7 +332,7 @@ Each editor reads the servers from its own file: In the Codex and OpenCode formats, register the same two commands as the sample: `serverpod mcp-server --server-dir _server` and `dart mcp-server`. -If you are using Cursor, enable the **Serverpod** and **Dart** MCP servers in your project settings (_Cursor Settings_ > _Tools & MCPs_). +If you are using Cursor, enable the **Serverpod** and **Dart** MCP servers: open **Customize** in the sidebar, click **MCPs**, and turn on both servers. ## What's new in 4.0 diff --git a/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md b/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md index 81e63759..397877b6 100644 --- a/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md +++ b/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md @@ -66,7 +66,7 @@ Next, open your newly created project with your favorite AI powered editor. Open :::important -If you are using Cursor, you will need to **enable the Serverpod and Dart MCP servers** in your project settings (_Cursor Settings_ > _Tools & MCPs_). +If you are using Cursor, you will need to **enable the Serverpod and Dart MCP servers**: open **Customize** in the sidebar, click **MCPs**, and turn on both servers. ::: diff --git a/versioned_docs/version-4.0.0/06-concepts/cli/commands/mcp-server/_mcp-server.md b/versioned_docs/version-4.0.0/06-concepts/cli/commands/mcp-server/_mcp-server.md index e8624248..7b86c8c7 100644 --- a/versioned_docs/version-4.0.0/06-concepts/cli/commands/mcp-server/_mcp-server.md +++ b/versioned_docs/version-4.0.0/06-concepts/cli/commands/mcp-server/_mcp-server.md @@ -1,5 +1,55 @@ # serverpod mcp-server -`serverpod mcp-server` starts a Model Context Protocol bridge to the `serverpod start` runner of a server project, letting an AI assistant build, run, and inspect your server. +`serverpod mcp-server` starts a Model Context Protocol bridge to the `serverpod start` runner of a server project. An agent can use it to create and apply migrations, reload the server and Flutter app, and read logs. The server directory is auto-detected from the current working directory. Pass `--server-dir` explicitly in monorepos that contain more than one server project. + +The bridge drives a running session, so start one with `serverpod start` before asking an agent to use these tools. The bridge itself can stay connected while the session stops and starts. + +## Set up your editor + +The `serverpod create` command writes the MCP configuration for the editors you select, so a new project needs no manual setup. Run `serverpod create .` in an existing project to add the same files. + +| Editor | File | +| --- | --- | +| Claude | `.mcp.json` | +| Cursor | `.cursor/mcp.json` | +| VS Code | `.vscode/mcp.json` | +| Antigravity | `.agents/plugins/serverpod-local/mcp_config.json` | +| Codex | `.codex/config.toml` | +| OpenCode | `opencode.json` | + +In Cursor, once the file is created, open **Customize** in the sidebar and click **MCPs**. There, make sure both the `serverpod` and `dart` servers are turned on. + +### Set up any other MCP client + +Serverpod registers two servers, its own bridge and the Dart MCP server. Any client that speaks MCP over stdio can run them, so write these two commands in whatever format your client expects. + +```json +{ + "mcpServers": { + "serverpod": { + "command": "serverpod", + "args": ["mcp-server", "--server-dir", "_server"] + }, + "dart": { + "command": "dart", + "args": ["mcp-server"] + } + } +} +``` + +The shape differs per editor. VS Code names the block `servers` rather than `mcpServers`. Antigravity and OpenCode name the Dart entry `dart-mcp-server`, and OpenCode puts both under an `mcp` block. Codex uses TOML. + +:::note +Module projects get only the Dart MCP server. A module has no runnable server, so there is no `serverpod start` session for the bridge to connect to. +::: + +## Migrations and your data + +The bridge exposes three migration tools. The `create_migration` and `create_repair_migration` tools write migration files without changing your database. Both accept a `force` parameter that proceeds past Serverpod's warning that a change may destroy data. The `apply_migrations` tool then applies the pending migrations to your database. + +:::warning +The `apply_migrations` tool takes no parameters and applies every pending migration, including one an agent created with `force`. Keep `serverpod start` in its default `development` run mode, because another mode loads that environment's database. Review each `apply_migrations` call before you approve it. +::: diff --git a/versioned_docs/version-4.0.0/11-upgrading/01-upgrade-to-four.md b/versioned_docs/version-4.0.0/11-upgrading/01-upgrade-to-four.md index 14b7fc9b..eda7da8c 100644 --- a/versioned_docs/version-4.0.0/11-upgrading/01-upgrade-to-four.md +++ b/versioned_docs/version-4.0.0/11-upgrading/01-upgrade-to-four.md @@ -332,7 +332,7 @@ Each editor reads the servers from its own file: In the Codex and OpenCode formats, register the same two commands as the sample: `serverpod mcp-server --server-dir _server` and `dart mcp-server`. -If you are using Cursor, enable the **Serverpod** and **Dart** MCP servers in your project settings (_Cursor Settings_ > _Tools & MCPs_). +If you are using Cursor, enable the **Serverpod** and **Dart** MCP servers: open **Customize** in the sidebar, click **MCPs**, and turn on both servers. ## What's new in 4.0