Sandbox Seed

What sandbox-seed MCP server does

The sandbox-seed MCP server coordinates record seeding between Salesforce orgs. A source org supplies records selected by an object and human-provided SOQL predicate; a target org must be a Salesforce sandbox. The tool follows related-object dependencies, maps source IDs to target IDs, and writes records through a staged process that accounts for parent ordering and circular relationships.

Its main MCP surface is a five-stage flow: start, analyze, select, dry-run, and run. The dry-run gate produces a reviewable plan before writes occur. The MCP responses contain metadata such as counts, object names, relationship information, file paths, and plan hashes, not record rows.

The package also includes a CLI. inspect explores Salesforce schema and dependency graphs, while seed runs the same seeding engine and safety gates from a terminal or CI environment. A session can stop at a dry-run report and resume later.

How it works

The tool begins with a source alias, target alias, Salesforce object, and SOQL WHERE predicate. During analysis, it describes the object graph and identifies related records. Optional parents and children can be selected before the plan is generated. The graph walker supports two-phase inserts for strongly connected components, which allows it to handle relationships such as Account and Contact that cannot be inserted in a simple linear order.

Salesforce CLI authentication supplies access to the configured org aliases. During execution, the tool maintains mappings between source and target IDs so foreign keys can point to the newly created target records. Re-runs can use persisted external-ID choices for objects that support them, routing those records through upsert behavior.

Record data is stored in an on-disk session store controlled by the tool. Sessions are kept under ~/.sandbox-seed/sessions/, while cross-run ID maps are stored under ~/.sandbox-seed/id-maps/. Dependency-description results use a cache under .sandbox-seeding/cache/ with a 24-hour lifetime.

Setup and configuration

Install Node.js 20 or later and the Salesforce CLI. Log in to both orgs with Salesforce CLI aliases, then register the sandbox-seed MCP server with an MCP host using npx:

{
  "mcpServers": {
    "sandbox-seed": {
      "command": "npx",
      "args": ["-y", "-p", "sandbox-seed", "sandbox-seed-mcp"]
    }
  }
}

The README specifically shows configuration locations for Cursor, Claude Desktop, and a project .mcp.json file. Restart the host after adding the entry. For terminal use, install the package globally with npm i -g sandbox-seed and run commands such as sandbox-seed inspect --object Case or sandbox-seed seed.

Tools and capabilities

The sandbox-seed MCP server provides a seed tool for the staged Salesforce copy workflow. Supported capabilities include:

• SOQL-predicate-based record selection
• Dependency-graph analysis and related-record selection
• Cross-org foreign-key remapping
• Two-phase inserts for circular dependency components
• Mandatory dry-run and explicit confirmation before writes
• Deterministic masking of selected PII, including a digit-shaped postal-code preset
• Snapshotting and restoration of target validation rules when that option is enabled
• Metadata-only MCP responses

The CLI adds read-only schema and dependency inspection, formatted graph output, dry-run-only execution, session resume, recovery, JSON output, and interactive or automatic confirmation options described in the package documentation.

Limitations and notes

The tool refuses writes when the target is not identified as a Salesforce sandbox. It also requires a real SOQL predicate in whereClause; an agent cannot substitute vague natural-language conditions such as “the biggest” or “recent ones.” A full SELECT statement is not accepted in that field.

The AI-boundary design prevents record rows from entering MCP responses, but the records still exist in the local session store. Protect the machine and those files according to your data-handling requirements. The source and target must also be authenticated through Salesforce CLI aliases before use.

A limit value is a safety cap rather than a SOQL LIMIT. Filters matching no records or exceeding the cap stop the workflow for correction. Validation rules can reject target inserts unless the supported snapshot/deactivate/restore option is enabled. Re-running against a non-clean sandbox may produce duplicate errors when an object lacks a usable external ID.