// Serverpod overview — what it is, project structure, how to work with. Always use at least once when working with projects that use Serverpod.
| name | serverpod-overview |
| description | Serverpod overview — what it is, project structure, how to work with. Always use at least once when working with projects that use Serverpod. |
Serverpod is an open-source backend framework for Flutter written in Dart. A Serverpod project consists of usually three packages:
my_project_server - the server code.
my_project_client - generated client code.
my_project_flutter - a Flutter app (imports the client).
There can also be packages that share code, e.g., my_project_shared.
The server exposes endpoint classes that the client calls via generated RPC client. Add methods to the endpoints, the code generation will recreate them on the client side. Models are defined in YAML and generate Dart classes for both server and client.
Serverpod projects use a Postgres database for persistence and include an ORM, caching, real-time streaming (using Dart streams), file uploads, scheduling (called future calls), logging, and a built-in web server (Relic). Each of these features have specific skills that you can use to get more details.
Most likely the server is already running with hot reload and serverpod generate --watch. NEVER attempt to start the server. The user is running the server with the serverpod start command (as an agent do NOT run this command, instead prompt the user to run serverpod start, if neccessary). Hot reload will update the generated code and quickly restart the server when files are changed.
ALWAYS use the MCP server instead of the command line. Use the MCP server to:
create_migration and apply_migrations for database (after you change data models).tail_server_logs to read logs from the server.tail_flutter_logs to read raw stdout/stderr from the Flutter app.hot_restart will reload the server and the Flutter app. ALWAYS call it after doing changes in the Flutter app that may not work with normal hot reload (which is automatically applied).serverpod generate.After generating the code, database migrations can be created by calling serverpod create-migration. Use ONLY if you cannot use the MCP.
# Use `--force` to create migrations with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-migration [--force] [--tag <tag>]
See the Serverpod Migrations skill for more details.
Checklist after doing changes:
dart analyze (dart MCP server)dart format (dart MCP server)serverpod MCP hot_restart if required (hot reload is done automatically). Will also hot restart Flutter appserverpod MCP tails_logs for any issuesServerpod web server (Relic) — REST APIs, webhooks, middleware, static files, server-rendered HTML, SPAs, Flutter web. Use when adding HTTP routes, serving web pages or web apps, intercepting requests, or working with the Relic web server.
Serverpod Authentication — Signing in users, verify if they are authenticated, assinging scopes (e.g., admin). Use when adding features that require the user to be signed in.
Serverpod ORM with PostgreSQL or SQLite — CRUD, filters, sorting, pagination, relations, transactions, raw SQL, client-side database. Use when querying the database or working with relations.
Serverpod logging — session.log, log levels, persistence, retention, console output. Use when adding logging or debugging server calls.
Serverpod database migrations — when and how to create/apply/repair migrations. Use whenever database schema changes are involved.
Real-time streaming in Serverpod — Stream parameters and return types, WebSocket lifecycle, error handling. Use when building real-time features, chat, live updates, or WebSocket streaming.