ERP Plugin Developer Docs

Appearance

Set up the SDK and connect to an environment ​

What you're doing ​

Before you can build anything you need the plugin SDK talking to your ERP. The SDK is two programs:

  • the erp CLI — scaffolds plugins, validates them, and publishes them to your ERP.
  • the erp-plugin-language MCP server — the thing your AI coding agent (Claude Code, Cursor, Codex) calls to look up schemas, widgets, and worked examples so it doesn't have to guess.

An environment (or env) is one named ERP you talk to — dev, staging, prod. The CLI remembers a base URL and a login token per env in ~/.erp/config.json, so you can switch between them with one command.

You do not need access to the ERP's source code. Everything the tools need to ground themselves — JSON Schemas, the catalog of platform capabilities, curated examples, these docs — ships in an authoring bundle that the SDK reads offline and can refresh from your ERP.

The complete sequence ​

bash
# 1. point the CLI at your ERP and give the env a name
erp env use dev --base-url https://erp.example.com

# 2. log in (opens your browser; RFC 8628 device-authorization grant)
erp login

# 3. confirm who you are and which tenant you're on
erp whoami

# 4. pull this env's authoring bundle into ~/.erp/cache/
erp env sync

# 5. install the MCP server config into the current project folder
erp mcp install

Until the SDK is published to npm you run it directly. Everywhere these docs say erp, substitute node <sdk>/tools/erp-cli/erp.mjs. Set a shell alias: alias erp='node /path/to/tools/erp-cli/erp.mjs'.

Line by line ​

erp env use dev --base-url https://erp.example.com creates an env named dev and makes it current. Run it again with a different name to add another env; erp env list shows them all with a * next to the current one. erp env use staging (no --base-url) just switches to an env you already defined.

erp login opens your browser, you approve the CLI, and an access token + refresh token are written to ~/.erp/config.json (file mode 0600). Networked commands auto-refresh an expired access token, so you rarely log in again. In CI, skip the browser: set ERP_TOKEN=<access token> and the CLI uses that instead.

erp whoami prints the env, base URL, tenant id, your user id, and your roles. This is the fastest check that your session is live and pointed where you think.

erp env sync downloads the env's authoring bundle (schemas, the frozen capability catalog, blocks, validators, docs, plus the live list of entity and theme names in your tenant) into ~/.erp/cache/<env>/. If your ERP doesn't expose the bundle endpoint yet this is a no-op and the SDK falls back to the bundle shipped inside the SDK package — you can keep going. Re-run it whenever your ERP is upgraded. erp env sync --check reports drift without downloading.

erp mcp install writes a .mcp.json in the current directory pointing at the erp-plugin-language MCP server. Your AI agent picks it up automatically the next time it opens this folder.

How to verify it worked ​

bash
erp whoami

Expected — a JSON blob like this (your values differ):

json
{
  "env": "dev",
  "baseUrl": "https://erp.example.com",
  "tenantId": 2,
  "valid": true,
  "userId": "you@example.com",
  "roles": ["HR Administrator", "Studio Staff"]
}

"valid": true means the token is good. Then check the MCP wiring:

bash
cat .mcp.json

You should see a server entry named erp-plugin-language. Restart your AI agent in this folder and ask it to call erp_list_schemas — it should return a list of schema names, not an error.

Common mistakes ​

SymptomCauseFix
erp whoami says "valid": falsetoken expired and no refresh tokenerp login again
could not reach <url>wrong base URL, or / mangled by Git Bash on Windowscheck erp env list; on Git Bash set MSYS_NO_PATHCONV=1
erp env sync downloads nothingyour ERP has no /api/v1/dev/bundle endpoint yetfine — the SDK's built-in bundle is used
AI agent can't see the erp_* tools.mcp.json written in a different folder, or agent not restartedrun erp mcp install in your project root, restart the agent
--tenant 5 "does not re-authenticate you" errors--tenant only overrides the header; your token must already be valid for that tenantlog in as a user who has access to that tenant