docs: Cover MCP setup in the 4.0 migration guide#666
Conversation
|
|
||
| VS Code's `.vscode/mcp.json` registers the same two servers but nests them under a `servers` key instead of `mcpServers`. | ||
|
|
||
| :::warning |
There was a problem hiding this comment.
Suggestion: this warning to commit your work sits below the serverpod create . block, so a reader who copies the command first can run it before seeing the caution. It reads better moved just above the command block (around line 148), so the warning comes before the action. The text itself is fine; it is just a block move.
| $ serverpod create . | ||
| ``` | ||
|
|
||
| Serverpod detects the existing project and adds the missing pieces without touching your source code. It registers the **Serverpod** and **Dart** MCP servers and installs the agent skills for the editor you select. The registration is written to `.mcp.json`, along with editor-specific files (`.cursor/mcp.json` and `.vscode/mcp.json`) in each editor's own format. The `.mcp.json` file looks like this: |
There was a problem hiding this comment.
Suggestion: .mcp.json is Claude's own file, not a shared one. In ide.dart, each selected editor gets its own file (.mcp.json for Claude, .cursor/mcp.json for Cursor, .vscode/mcp.json for VS Code), so a Cursor-only user gets no .mcp.json at all and could go looking for a file that is not there. Reframing avoids that (and fixes "editor" to "editors", since you can select more than one):
| Serverpod detects the existing project and adds the missing pieces without touching your source code. It registers the **Serverpod** and **Dart** MCP servers and installs the agent skills for the editor you select. The registration is written to `.mcp.json`, along with editor-specific files (`.cursor/mcp.json` and `.vscode/mcp.json`) in each editor's own format. The `.mcp.json` file looks like this: | |
| Serverpod detects the existing project and adds the missing pieces without touching your source code. It registers the **Serverpod** and **Dart** MCP servers and installs the agent skills for the editors you select. Each selected editor gets a config file in its own format: `.mcp.json` for Claude, `.cursor/mcp.json` for Cursor, and `.vscode/mcp.json` for VS Code. For Claude, `.mcp.json` looks like this: |
| @@ -141,15 +141,50 @@ The first run compiles the native build hooks (this can take about 30 seconds) a | |||
|
|
|||
| Beyond the server, `serverpod start` also launches the project's Flutter app. By default it uses Flutter's `web-server` device and opens your browser. Pass `--flutter-device <name>` to target a specific device. For IDE debugging, projects scaffolded with 3.5 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 3.5 scaffold if you want the same setup. | |||
There was a problem hiding this comment.
Comment (pre-existing, outside this diff): two stale lines worth a quick fix while this file is open. This line mentions --flutter-device <name>, which is not a real serverpod start flag (only --flutter / --no-flutter exist). And line 25 pins dart install serverpod_cli 3.5.0-beta.9, while the latest 3.5 beta is beta.12. Up to you whether to fold these in here or leave them for a follow-up.
There was a problem hiding this comment.
is it not 4.0.0-beta.0 ?
There was a problem hiding this comment.
Oh, yeah it should be 4.0.0-beta.0
developerjamiu
added
documentation
Zfinix
changed the title
2 participants
Summary
The 3.5 migration guide told upgrading users to set up the agentic workflow with
dart install skills+skills get, which installs the skills but never registers the MCP servers. New projects get their MCP config fromserverpod create, so migrating users were left without the Serverpod and Dart MCP servers.This updates the "Set up the agent workflow" section to lead with
serverpod create ., which configures both MCP servers and installs the skills in one step (the same setup a new project gets). It also:.mcp.jsonand notes VS Code's.vscode/mcp.jsonuses aserverskey instead ofmcpServers.dart install skills/skills getas a skills-only refresh path.Verified against the Serverpod CLI 3.5.0-beta.10:
serverpod create .is non-destructive on an existing project (runs the upgrade flow, configures the MCP servers, installs skills), and the--ideeditor list and.mcp.jsonstructure match the live output.Closes #583