Provides tools for planning and executing seeding runs against a PostgreSQL database, generating realistic, relationally valid test data from its live schema.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Seedfast MCP Server Create a seeding plan for my database based on its schema"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Seedfast fills a PostgreSQL database with realistic, relationally valid test data generated from its live schema, so a team that cannot put production data into development still gets an environment that behaves like production.
This repository is the public integration surface for its MCP server. You will find the client configuration, the tool reference and a smoke test here. The engine and the CLI themselves are closed-source and ship through npm and Homebrew.
Published in the official MCP registry as st.seedfa/seedfast.
Nothing separate to install. The MCP server is built into the Seedfast CLI and runs straight from npx:
{
"mcpServers": {
"seedfast": {
"command": "npx",
"args": ["-y", "seedfast@latest", "mcp"],
"env": {
"SEEDFAST_API_KEY": "sfk_live_your_api_key_here"
}
}
}
}That block goes into claude_desktop_config.json for Claude Desktop, .cursor/mcp.json for Cursor, or the equivalent file for VS Code and Claude Code. Client-by-client paths are in the MCP setup guide.
Prefer a local binary? Install the CLI and point command at seedfast with args: ["mcp"] instead:
brew install seedfast-ai/tap/seedfast # macOS, Linux
npm install -g seedfast # any platform with Node.jsRelated MCP server: mcp-backend
Variable | Required | What it does |
| yes | API key created in the Seedfast dashboard |
| no | Path to a SQLite file. Without it, runs and plans live in memory and disappear when the server exits |
Thirteen tools cover the whole loop of planning a seed, running it and inspecting what happened.
Tool | What it does |
| Checks CLI health and whether authentication is configured |
| Tests a database connection before anything is written |
| Reads the live schema of the target database |
| Builds a seeding plan from a scope description |
| Executes a seeding run |
| Polls a run in progress |
| Aborts a run |
| Answers a question the run raised while it was waiting for input |
| Lists saved plans |
| Reads one saved plan |
| Saves a new plan |
| Edits a saved plan |
| Removes a saved plan |
URI | Media type | Contents |
|
| Summary of a seeding run |
|
| Event log of a seeding run |
|
| The question a run is waiting on, while it is in |
|
| Details of a saved plan |
Two prompts ship with the server: seed-production-db, which takes a scope and a description of the target database, and scope-examples, which turns a use case into example scopes.
The smoke test starts the published package over stdio, completes an MCP handshake and lists the tools. It needs no API key, since it never reaches the backend:
node scripts/smoke-test.mjsExpected output ends with the protocol version the server negotiated and the number of tools it advertises.
Seedfast works with PostgreSQL today. Going PostgreSQL-first was deliberate, since its constraint and relationship system is the richest one out there and that is exactly where generating believable data gets hard. Support for MySQL, Oracle and SQLite is in development.
Questions and bug reports: support@seedfa.st
MIT for the contents of this repository. The Seedfast CLI is distributed under the same license; its engine runs as a hosted service.
Probes a PostgreSQL database for reachability by opening a connection pool and issuing a ping with a 10-second timeout. Returns a short text line stating success or failure for the supplied DSN (credentials are masked in the output). Use this before seedfast_plan or seedfast_run to catch bad DSNs, firewall issues, or wrong credentials without incurring a planning or seeding round-trip. Does not require SEEDFAST_API_KEY. Next: on success, call seedfast_plan to preview a seeding plan or seedfast_run to execute one.
| Name | Required | Description | Default |
|---|---|---|---|
| dsn | Yes | PostgreSQL connection string (e.g., postgres://user:pass@host:5432/db). Credentials are masked in log/response output. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly: opening a connection pool, issuing a ping, the 10-second timeout, the short text output format, credential masking, and no API key requirement. This gives an agent a complete picture of what will happen and what is safe to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and every sentence earns its place: behavior first, output next, use-case next, auth note, then onward guidance. No filler or repeated schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter probe tool with no output schema and no annotations, this description is complete: it defines purpose, behavior, output, timeout, credentials, authentication requirements, and the next recommended actions. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the dsn parameter is already well described with a format example. The description adds a small amount of value by referring to 'the supplied DSN' and noting credentials are masked, but it does not need to compensate for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Probes'), a concrete resource (PostgreSQL database via DSN), and the mechanism (connection pool + ping with 10-second timeout). It also differentiates from siblings by naming seedfast_plan and seedfast_run as subsequent tools, making the tool's role in the workflow unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this tool before seedfast_plan or seedfast_run to catch bad DSNs, firewall issues, and wrong credentials without paying for a planning or seeding round-trip. It also states that SEEDFAST_API_KEY is not required, giving clear authorization context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnoses whether the Seedfast CLI environment is healthy and ready to run seedings. Returns a multi-line text summary: CLI status and version, binary path, whether SEEDFAST_API_KEY is configured, platform (GOOS/GOARCH), Go runtime version, and MCP server version. Call this FIRST before any other seedfast_* tool — it surfaces misconfigurations (missing CLI, missing API key) early and in plain language. Next: if status is OK, call seedfast_connections_test to verify database reachability before seedfast_plan or seedfast_run.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool surfaces misconfigurations early and returns a multi-line summary with specific fields. While it doesn't explicitly state that it has no side effects (e.g., is read-only), the diagnostic nature implies this, and the description provides enough behavioral context for the agent to use it correctly. It could be slightly more explicit about not modifying anything, but it is quite informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, both highly informative. The first sentence states the purpose and the return content, and the second provides crucial usage guidance with the next step. It is front-loaded with the purpose and then flows into usage. There is no wasted words or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters, no output schema, and no annotations, the description must be self-contained. It fully explains what the tool does, what it returns (including specific fields), and how it fits into the workflow (first step, then connections_test). The agent has everything it needs to invoke the tool correctly and interpret the result. The description is complete for a zero-parameter diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline for parameter semantics is 4. The description doesn't need to explain any inputs; it focuses on the output and usage, which is appropriate. It does describe the return content in detail, but that's not parameter-related. The schema already covers the fact that there are no parameters, and the description adds no unnecessary parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: diagnosing the health of the Seedfast CLI environment. It specifies the verb ('diagnoses'), the resource ('Seedfast CLI environment'), and the outcome ('ready to run seedings'). It also distinguishes itself from sibling tools by being the mandatory first check, and explicitly lists the information it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage instructions: 'Call this FIRST before any other seedfast_* tool' and tells the agent exactly what to do next: 'if status is OK, call seedfast_connections_test to verify database reachability before seedfast_plan or seedfast_run.' This clearly differentiates when to use this tool versus the siblings and provides a decision tree for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generates a seeding plan for the given database and scope WITHOUT writing any data, then stores the plan in the current MCP session for later reuse. Returns a text block containing the generated plan ID, the scope echoed back, a table list with count, and an optional human-readable preview. Use this when the user wants to review what would be seeded before committing — e.g., to inspect which tables the scope covers. Requires SEEDFAST_API_KEY configured in MCP env. For scope-writing guidance, request the scope-examples prompt. Next: call seedfast_plan_get or read the seedfast://plans/{planId} resource to inspect the plan, then seedfast_run with planId to execute it.
| Name | Required | Description | Default |
|---|---|---|---|
| dsn | Yes | PostgreSQL connection string for the target database. | |
| scope | Yes | Plain-text description of what to seed (e.g., 'seed only the sales schema', 'populate users and orders'). Interpreted server-side by the backend LLM — do not pre-parse or validate it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the critical non-destructive behavior ('WITHOUT writing any data'), the requirement of SEEDFAST_API_KEY, and the side effect of storing the plan in the MCP session. It also describes the return format (text block with plan ID, scope, table list, preview). The only minor gap is not detailing what happens to a previously stored plan with the same ID, but the disclosure is strong overall.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the core purpose and non-destructive behavior, then covers return format, use case, prerequisites, and next steps. It's efficient and every sentence earns its place. It could be slightly more structured (e.g., separate sentences for workflow), but it's not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 required params, no output schema, and no annotations, the description is remarkably complete. It covers what the tool does, what it returns, when to use it, prerequisites (API key), and the follow-up workflow. An agent has everything needed to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds a useful note about the scope parameter being 'interpreted server-side by the backend LLM — do not pre-parse or validate it,' which is valuable behavioral guidance beyond the schema. However, it doesn't add much about dsn beyond what the schema says. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds a small but meaningful extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Generates a seeding plan'), the resource ('for the given database and scope'), and a key behavioral distinction: it does NOT write data. It also names the sibling tool it is not (seedfast_run) and explains the plan is stored for later reuse. This clearly differentiates it from siblings like seedfast_plan_create and seedfast_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'when the user wants to review what would be seeded before committing — e.g., to inspect which tables the scope covers.' It also provides a clear next-step workflow: call seedfast_plan_get or read the seedfast://plans/{planId} resource, then seedfast_run with planId. It even mentions requesting the `scope-examples` prompt for scope-writing guidance. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stores a manually-crafted seeding plan in the current MCP session without calling the backend planner. Returns a text block with the new plan ID, scope, and table list. Use this when the caller already knows exactly which tables to seed (e.g., derived from a user prompt or a previous run) and wants to skip the planner round-trip, or to construct a plan for seedfast_run with planId. At least one entry in tables is required. Does not require SEEDFAST_API_KEY. Next: call seedfast_run with planId to execute, or seedfast_plan_update to refine the plan.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | Plain-text scope description (e.g., 'seed only sales schema'). Stored verbatim alongside the plan. | |
| tables | Yes | Non-empty list of table names to seed (e.g., ['users', 'orders']). | |
| preview | No | Optional human-readable summary shown by seedfast_plan_get and seedfast_plans_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden — and it delivers. It discloses the session-scoped storage behavior (no backend call), the return format ('a text block with the new plan ID, scope, and table list'), the auth requirement ('Does not require SEEDFAST_API_KEY'), and the mandatory minimum of one table entry. For a mutation-like tool with zero annotation coverage, this is unusually complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with zero filler: purpose, return format, when-to-use condition, requirement, auth note, and next steps. The core purpose and scope constraint are front-loaded before the usage guidance. Every clause earns its place, including the useful auth disclosure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no annotations, the description explicitly covers the return value, the invocation context, prerequisites (tables requirement), auth posture, and downstream workflow. For a 3-parameter create tool this is complete — an agent can select and call it correctly without opening any sibling schemas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents each parameter well (scope stored verbatim, tables as non-empty list, preview shown by seedfast_plan_get/plans_list). The description's 'At least one entry in tables is required' restates the schema's 'Non-empty list' constraint rather than adding new meaning. Baseline 3 is appropriate since structured data does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a specific verb+resource: 'Stores a manually-crafted seeding plan in the current MCP session without calling the backend planner.' This clearly distinguishes it from sibling tools: seedfast_run executes plans, seedfast_plan_update refines them, seedfast_plan_delete removes them. The 'without calling the backend planner' clause additionally separates it from planner-backed plan generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this when the caller already knows exactly which tables to seed... and wants to skip the planner round-trip.' It names alternatives directly ('Next: call seedfast_run with planId to execute, or seedfast_plan_update to refine the plan') and gives a concrete caller scenario (derived from user prompt or previous run). The when-not case (caller doesn't know tables) is strongly implied by the stated precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently removes a stored plan from the current MCP session. Returns a short text line confirming deletion; returns an error when the ID is unknown or the delete fails. This is a destructive action — the plan cannot be recovered through this tool. It does NOT cancel or affect any seeding run that was previously started from the plan. Use only when the user explicitly wants to discard a plan. Does not require SEEDFAST_API_KEY. Next: call seedfast_plans_list to confirm the plan is gone.
| Name | Required | Description | Default |
|---|---|---|---|
| planId | Yes | Plan ID to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly: it declares permanence, irrecoverability, return behavior, error conditions, independence from seeding runs, and that no API key is required. This is exemplary disclosure for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds distinct value: purpose, return/error behavior, destructiveness, run-cancel distinction, usage condition, auth requirement, and a verification next step. It is slightly long but tightly structured and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter delete tool with no output schema, the description covers the outcome, failure modes, side-effect non-impact, authentication context, and a post-call verification step. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes planId as 'Plan ID to delete' with 100% coverage, so the schema already carries the parameter meaning. The description adds the error case for an unknown ID, but provides no additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('removes') and a specific resource ('stored plan from the current MCP session'), clearly distinguishing this from canceling a run. It also states the outcome, errors, and irreversibility, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit condition for use ('Use only when the user explicitly wants to discard a plan') and explicitly excludes a related behavior ('does NOT cancel or affect any seeding run'). It stops short of naming the alternative cancel-run tool, but the guidance is still clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a single stored seeding plan by ID. Returns a text block with the plan ID, scope, full table list, optional human-readable preview, and created/updated timestamps; returns an error when the ID is unknown. Use this to inspect a plan's table set before executing it, or to show the user what a plan contains. Does not require SEEDFAST_API_KEY (reads local session state). Next: call seedfast_run with planId to execute, seedfast_plan_update to modify, or seedfast_plan_delete to remove it.
| Name | Required | Description | Default |
|---|---|---|---|
| planId | Yes | Plan ID (as shown by seedfast_plans_list or returned by seedfast_plan / seedfast_plan_create). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses the return shape (a text block with specific fields), error behavior for unknown IDs, and that no SEEDFAST_API_KEY is needed because it 'reads local session state.' This is solid coverage, though it could be even more explicit about side-effect-free/read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. The main action is first, return and error behavior come second, and usage/auth/next-steps are third. Every sentence earns its place, and the structure front-loads the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with no output schema, the description is complete. It covers the return contents, unknown-ID error, authentication/state requirements, intended use cases, and related next steps. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains that planId is the plan ID as shown by seedfast_plans_list or returned by seedfast_plan / seedfast_plan_create. The description adds no additional meaning about the parameter beyond 'by ID,' so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Retrieves a single stored seeding plan by ID.' It clarifies the scope as one plan, distinct from list tools, and enumerates the returned contents (plan ID, scope, full table list, preview, timestamps), so an agent can tell it apart from siblings like seedfast_plans_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases: 'inspect a plan's table set before executing it' or 'show the user what a plan contains.' It also names follow-up alternatives (seedfast_run, seedfast_plan_update, seedfast_plan_delete). It does not explicitly state when not to use it, such as listing all plans via seedfast_plans_list, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists seeding plans stored in the current MCP session (in-memory; plans do not persist across MCP server restarts). Returns a text block with up to limit plans, each showing ID, scope, table count with names, and created/updated timestamps; returns 'No plans found' when the session has none. Use this to discover plan IDs before calling seedfast_plan_get, seedfast_plan_update, seedfast_plan_delete, or seedfast_run with planId. Does not require SEEDFAST_API_KEY. Next: pick an ID and call seedfast_plan_get for full details, or seedfast_run to execute.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of plans to return. Defaults to 50 when omitted or non-positive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral burden. It discloses in-memory storage, non-persistence across restarts, the text block return format, the limit behavior, and the 'No plans found' response. It also clarifies that no API key is needed, which is a meaningful behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but well-organized: it starts with purpose, then output details, then usage guidance. Every sentence adds value, though it could be tightened slightly without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter and no output schema, the description covers everything an agent needs: what it returns, the format, the limit, the empty response, and how to proceed. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter 'limit' is already documented with its default behavior. The description reinforces that it caps the number of plans returned but adds no new semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Lists') and resource ('seeding plans stored in the current MCP session'), with an explicit in-memory scope. It distinguishes itself from sibling tools by focusing on listing, while others handle get/update/delete/run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs when to use the tool: 'Use this to discover plan IDs before calling seedfast_plan_get, seedfast_plan_update, seedfast_plan_delete, or seedfast_run with planId.' It also notes that no API key is required, and provides a next-step suggestion, leaving no ambiguity about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modifies an existing stored plan in place. Returns a text block confirming the update with the plan ID, scope, table list, and new updated-at timestamp; returns an error when the ID is unknown. Only non-empty/non-zero fields in the request overwrite the stored plan — omitted fields are preserved (there is no way to clear preview or scope to empty via this tool). Use this to adjust a plan's tables or scope before executing with seedfast_run. Does not require SEEDFAST_API_KEY. Next: call seedfast_plan_get to verify, or seedfast_run with planId to execute.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Replacement scope description. When non-empty, overwrites the stored scope; empty string is treated as 'leave unchanged'. | |
| planId | Yes | Plan ID to update. | |
| tables | No | Replacement list of tables. When provided and non-empty, overwrites the stored tables; when omitted, existing tables are preserved. | |
| preview | No | Replacement preview text. When non-empty, overwrites the stored preview; empty string is treated as 'leave unchanged'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and covers partial-overwrite semantics, empty-field preservation, the inability to clear fields, auth requirements, return confirmation details, and unknown-ID errors. This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, and every sentence earns its place: return/error behavior, update semantics, usage context, auth, and follow-up actions. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes return shape, error case, update semantics, auth, and suggested next steps. Given the rich schema and no output schema, nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents each parameter with 100% coverage, so the baseline is solid. The description adds a unifying partial-update rule ('Only non-empty/non-zero fields...') and the no-clear limitation, which is meaningful additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Modifies an existing stored plan in place'), names the resource, and distinguishes itself from plan_create, plan_delete, and plan_get siblings. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions the tool for adjusting a plan's tables or scope 'before executing with seedfast_run' and suggests verification via seedfast_plan_get. It does not explicitly enumerate exclusions against plan_create or plan_delete, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kicks off an asynchronous seeding run against the target database. Returns immediately with a text block containing the new runId, initial status (pending), the plan ID if supplied, and the effective scope; the seeding itself runs in the background — poll seedfast_run_status or subscribe to the seedfast://runs/{runId}/summary and seedfast://runs/{runId}/log resources for progress. If planId is provided, the scope is auto-generated from that plan's tables and the scope argument is ignored; otherwise scope is required. If idempotencyKey matches a prior run, that existing run is returned instead of starting a new one. Use this once the user has approved a plan (or wants direct execution). Requires SEEDFAST_API_KEY configured in MCP env. For production-safe workflows, request the seed-production-db prompt first. Next: seedfast_run_status to poll, or seedfast_run_cancel to abort.
| Name | Required | Description | Default |
|---|---|---|---|
| dsn | Yes | PostgreSQL connection string for the target database. | |
| scope | No | Plain-text scope description. Required unless planId is provided; ignored when planId is set (scope is derived from the plan's tables). | |
| planId | No | ID of a plan previously produced by seedfast_plan or seedfast_plan_create. When set, the run seeds exactly those tables and the scope argument is overridden. | |
| idempotencyKey | No | Caller-chosen key for safe retries. If a prior run was started with the same key, that run is returned and no new run is created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers. It discloses asynchronous execution, immediate return contents (runId, pending status, plan ID, effective scope), background running, progress via polling/subscriptions, idempotencyKey behavior, and the required SEEDFAST_API_KEY. This is far beyond the schema and gives an agent a clear mental model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: primary action, return behavior, monitoring, plan/scope rules, idempotency, usage timing, API key requirement, and next-step routing. It is front-loaded with the main purpose and stays focused despite covering a complex operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an async, mutating run tool with no annotations and no output schema, the description is nearly complete: it covers the DSN requirement, plan/scope interaction, idempotency, what is returned, how to monitor, how to cancel, and the API key prerequisite. Minor gaps like error handling or explicit destructive-effect disclosure exist, but not enough to seriously impair an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the input schema already explains the planId/scope relationship and idempotency behavior. The description reiterates these same caveats but doesn't add deeper meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description nails the core action: 'Kicks off an asynchronous seeding run against the target database.' It clearly distinguishes this from siblings like seedfast_run_status (polling), seedfast_run_cancel (aborting), and seedfast_plan (plan creation), so an agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is present: 'Use this once the user has approved a plan (or wants direct execution).' It also directs the agent to the next steps—poll seedfast_run_status or cancel with seedfast_run_cancel—and mentions the production-safe prompt for safe workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answers a pending question for a run that is in state 'awaiting_input'. The CLI forwards backend questions (scope validation issues, replans) to this MCP server via subprocess stdio and blocks for up to 5 minutes on a reply. Call this tool with the runId, the questionId from seedfast_run_status (or the seedfast://runs/{runId}/pending_question resource), and an answer object. Set answer.human_answer=true to approve the current plan/scope as-is; set human_answer=false and supply answer.raw with a textual refinement (e.g., 'seed only the org schema') when the plan should be adjusted. Returns a short text confirmation. On success the run transitions back to 'running'; poll seedfast_run_status to observe progress. Does not require SEEDFAST_API_KEY.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | Run ID returned by seedfast_run (the run must be in state 'awaiting_input'). | |
| answer | Yes | Answer payload: set human_answer=true to approve, otherwise provide refined scope in raw. | |
| questionId | Yes | Question ID from the pending_question resource or from seedfast_run_status output. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: it explains the CLI blocks up to 5 minutes, the run transitions back to 'running' on success, returns a short text confirmation, and does not require SEEDFAST_API_KEY. It also explains the human_answer true/false behavioral distinction, which is beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately detailed for a tool with a nested object parameter and no annotations, and it is front-loaded with the core purpose. Every sentence adds useful information: source of IDs, answer semantics, blocking behavior, state transition, return value, and auth requirement. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested answer object, absence of annotations, and absence of an output schema, the description is remarkably complete. It covers all required inputs, exact answer-flag semantics, expected return, post-success behavior, how to observe progress, and auth. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context on top: runId must come from a run in 'awaiting_input', questionId is sourced from seedfast_run_status or the pending_question resource, and answer.raw is illustrated with a concrete example. This justifies above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Answers a pending question') with an explicit precondition (run state 'awaiting_input'), and clearly situates it among siblings as the tool for responding to backend questions. No ambiguity exists about what resource it operates on or why it differs from run_cancel, run_status, or the plan tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use context: the run must be in 'awaiting_input', and questionId should come from seedfast_run_status or the pending_question resource. It does not explicitly name alternative tools or state when-not-to-use, but the conditional context is strong enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Requests cancellation of a pending or running seeding operation. Returns a text line confirming cancellation, or — if the run is already completed/failed/cancelled — a message that it is not cancellable (no error). This is a destructive action against the run: partial inserts already written to the database are NOT rolled back. Use only when the user explicitly asks to stop a run or when a runaway operation must be aborted. Does not require SEEDFAST_API_KEY. Next: call seedfast_run_status to confirm the final state.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | Run ID returned by seedfast_run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden — and it delivers. It discloses the destructive nature ('destructive action against the run'), the non-rollback side effect ('partial inserts already written... NOT rolled back'), the non-error return path for terminal states, and the auth requirement ('Does not require SEEDFAST_API_KEY'). This is exemplary disclosure for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: core action, return behavior, destructive side effect, usage condition, auth note, and next step. The most important safety information (destructive, no rollback) is front-loaded before usage guidance. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description must explain return values and behavior — it does ('Returns a text line confirming cancellation, or... a message that it is not cancellable'). It also covers the side effects, when to use, auth, and the follow-up call. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single runId parameter is fully documented in the schema as 'Run ID returned by seedfast_run.' With full coverage, the baseline is 3, and the description adds no parameter-specific detail beyond what the schema already provides. This is appropriate; the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Requests cancellation of a pending or running seeding operation.' The description distinguishes itself from siblings like seedfast_run_status by describing the unique no-error behavior for terminal states, which clearly separates it from status-checking and other run-management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use only when the user explicitly asks to stop a run or when a runaway operation must be aborted.' It also implies when-not by disclosing that completed/failed/cancelled runs are not cancellable, and routes the agent forward with 'Next: call seedfast_run_status to confirm the final state.' No ambiguity about when this tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports the current state and progress of a seeding run by ID. Returns a text block containing: run ID, state (pending/running/completed/failed/cancelled), scope, started/completed timestamps, progress (completed vs total tables with percent, total rows, failed count, currently-seeding table), any error message, and — once finished — a summary block with success flag, totals, and elapsed milliseconds. Use this to poll an async seedfast_run; it is safe to call repeatedly. Does not require SEEDFAST_API_KEY (reads local in-memory state). Next: if state is still running, poll again; if failed, inspect the error and failed-tables map; if completed, the run is done.
| Name | Required | Description | Default |
|---|---|---|---|
| runId | Yes | Run ID returned by seedfast_run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the tool reads local in-memory state, requires no SEEDFAST_API_KEY, is safe to call repeatedly, and returns a detailed text block including error and summary data. This gives an agent full confidence about side effects and polling behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and return contents, then usage policy, then next-step guidance. Every sentence contributes distinct value: what it returns, when/how to use it, auth behavior, and follow-up actions. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description needed to explain return values and operational behavior—and it does. It covers the returned fields, polling safety, auth requirements, and what to do based on each terminal state. An agent has everything needed to invoke and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the sole parameter as the run ID returned by seedfast_run, so schema coverage is 100%. The description adds context that the status lookup is "by ID" but does not add format, constraints, or additional parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Reports the current state and progress of a seeding run by ID." It clearly identifies this as a status/polling tool, and the content distinguishes it from siblings like seedfast_run (which starts a run) and seedfast_run_cancel (which cancels one).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says "Use this to poll an async seedfast_run" and states it is safe to call repeatedly. It also provides post-call decision guidance for running/failed/completed states. It does not explicitly name alternatives to exclude, but the usage context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Introspects a PostgreSQL database schema — lists tables, columns, primary keys, foreign keys, and approximate row counts. Returns a JSON object with a tables array; each entry has name (schema-qualified), columns (name, data_type, nullable, default), primary_key, foreign_keys (columns, references_table, references_columns), and approximate_row_count. Row counts come from pg_class.reltuples and are APPROXIMATE — they may be stale between ANALYZEs and may be -1 on never-analyzed tables. Implementation invokes seedfast schema --json as a subprocess with a 30s timeout. Call this before writing a scope description — it helps you understand table relationships and size so you can craft a precise scope; especially useful for large databases where you want to target specific tables. Does not require SEEDFAST_API_KEY. The dsn argument is optional — when omitted, the server falls back to SEEDFAST_DSN or DATABASE_URL from its environment. Next: use the schema info to write a scope string, then call seedfast_plan with that scope. For scope-writing guidance, also request the scope-examples prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| dsn | No | PostgreSQL connection string. When omitted, the MCP server falls back to SEEDFAST_DSN, then DATABASE_URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does substantial work: it states the output shape, that row counts are approximate and may be stale or -1 before ANALYZE, that a subprocess with a 30s timeout is used, and that no SEEDFAST_API_KEY is required. It does not state side effects explicitly, but 'Introspects' implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence adds value: return format, approximation caveat, implementation timeout, auth requirement, usage context, and next steps. It is front-loaded with the core purpose and logically progresses from what to when to how.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is remarkably complete: it documents return structure, row-count accuracy caveats, execution timeout, environment fallbacks, and downstream workflow guidance. An agent has everything necessary to call it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter dsn is already fully documented in the schema (100% coverage), so the baseline is 3. The description reinforces optionality and the fallback order (SEEDFAST_DSN, then DATABASE_URL), adding modest clarity but no wholly new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Introspects') and resource ('PostgreSQL database schema'), then enumerates exactly what is listed (tables, columns, keys, row counts). This clearly distinguishes it from sibling planning/run tools, which operate on scopes and executions rather than database introspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Call this before writing a scope description' and gives a concrete next step: use the schema info to write a scope, then call seedfast_plan. It also notes when it is especially useful (large databases targeting specific tables). It does not name alternatives to avoid, but the sequencing guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.6.4seedfast_connections_testseedfast_doctorseedfast_planseedfast_plan_createseedfast_plan_deleteseedfast_plan_getseedfast_plan_updateseedfast_plans_listseedfast_runseedfast_run_answerseedfast_run_cancelseedfast_run_statusseedfast_schema_infoScored across 13 tools
Each tool maps to a distinct step in the seeding workflow: environment health, connectivity, schema inspection, plan CRUD, and run management. The only mild ambiguity is between seedfast_plan and seedfast_plan_create, but their descriptions clearly separate backend-generated plans from manually stored ones.
All tools share the seedfast_ prefix and mostly follow a predictable <resource>_<action> pattern such as plan_get, plan_delete, run_status, and run_cancel. A few core tools break that pattern (seedfast_doctor, seedfast_plan, seedfast_run, seedfast_schema_info), but they are recognizable primary actions rather than a chaotic mix.
13 tools is well within the ideal range and each one fills a distinct role across preflight checks, schema introspection, plan management, and run lifecycle. There is no redundant or padding tool.
The set covers the full seeding workflow: diagnose, test connectivity, inspect schema, generate/manage plans, execute runs, monitor progress, cancel, and answer interactive prompts. The only notable gap is the lack of a run-listing tool, but run IDs are returned at creation and seedfast_run_status covers monitoring.
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
MCP server for interacting with the Supabase platform
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
