This guide explains how to set up Claude Code as your external app building agent for Simplifier projects. Each project or application should live in its own directory with its own MCP configuration, cloned from the Simplifier App Editor.
Prerequisites
Before you begin, make sure the following are installed and available on your machine:
- Node.js (LTS version, includes npx)
- Git
- Claude Code CLI — install via:
npm install -g @anthropic-ai/claude-code - An Anthropic account with access to the Claude Opus and Claude Sonnet models
- Access to your Simplifier App Editor (to clone the project Git repository)
- A valid Simplifier Token from your Simplifier instance (see Step 3.2 below)
- For Spec Kit (optional, Step 7): uv (or pipx) to install the specify CLI
Step 1 — Create a New Project Directory
For each project or application, create a dedicated directory on your machine. This keeps MCPs, configuration, and Git history isolated per app.
mkdir ~/simplifier-projects/<your-app-name>
cd ~/simplifier-projects/<your-app-name>Important: Do not mix multiple Simplifier apps in the same directory. Each app needs its own folder so that MCPs and Claude Code context stay clean.
Step 2 — Clone the Project Git Repository from the Simplifier App Editor
- Open your app in the Simplifier App Editor.
- Create a new App with Version 2.
- Open the Git panel and copy the repository URL of your application.
- In your terminal, clone the repository into the directory you just created:
git clone <simplifier-app-git-url> .The trailing
.clones the repo into the current directory. - Verify the clone:
git status
Step 3 — Enter the Project Directory and Add MCPs
All MCP servers must be added from inside the project Git folder so they are scoped to this app only. Use the claude mcp add CLI command.
3.1 — Start Claude Code in the project folder (one-time, to initialize)
cd ~/simplifier-projects/<your-app-name>
claudeExit again with /exit once it has initialized.
3.2 — Add the required MCP servers via CLI
Run the following commands inside the project directory:
Simplifier MCP — Connectors, Business Objects, Datatypes, SAP Systems
Reference: https://github.com/simplifier-ag/simplifier-mcp
You need two values:
SIMPLIFIER_BASE_URL— e.g.https://<yourinstance>-dev.simplifier.cloud(on-premise users use their own dev URL).SIMPLIFIER_TOKEN— your current SimplifierToken from the logged-in Simplifier session.
Install via npx:
claude mcp add simplifier npx @simplifierag/simplifier-mcp@latest
--env SIMPLIFIER_TOKEN=<your-current-simplifier-token>
--env SIMPLIFIER_BASE_URL=https://<yourinstance>-dev.simplifier.cloudAlternative — via Docker:
claude mcp add simplifier-docker docker -- run --rm -i
--env SIMPLIFIER_TOKEN=<your-current-simplifier-token>
--env SIMPLIFIER_BASE_URL=https://<yourinstance>-dev.simplifier.cloud
simplifierag/simplifier-mcp:latestToken rotation: Every time you log in to Simplifier, your
SIMPLIFIER_TOKENchanges. After each new login you must:
- Exit Claude Code
- Remove the MCP:
claude mcp remove simplifier- Re-add it with the new token (command above)
- Restart Claude Code
If the Simplifier MCP fails to connect on startup, an error page opens in your browser with details and fix suggestions.
Fiori MCP Server — SAP Fiori application scaffolding & modification
claude mcp add fiori-mcp-server -- npx -y @sap/fiori-mcp-server@latestUI5 MCP Server — SAPUI5 / OpenUI5 development, linting, API reference
claude mcp add ui5-mcp-server -- npx -y @ui5/mcp-server@latestPlaywright MCP — Browser automation & end-to-end testing
claude mcp add playwright -- npx -y @playwright/mcp@latest3.3 — Verify the MCP registration
claude mcp listYou should see all added MCPs listed with status connected:
simplifier(orsimplifier-docker)fiori-mcp-serverui5-mcp-serverplaywright
Step 4 — Init the Simplifier Project
Execute the init command within Claude Code:
/init-simplifierThis command walks you through:
- Setting the Simplifier instance base URL in
.env - Running
pnpm installto fetch UI5 tooling - Starting the dev server with
pnpm run start(app available athttp://localhost:12345/index.html) - Registering the Simplifier, Playwright, and UI5 MCPs scoped to this project
- Documenting MCP usage in
CLAUDE.md/AGENTS.md
The
/init-simplifiercommand lives in.claude/commands/init-simplifier.mdin the project repo.
Step 5 — The Two-Mode Workflow: Plan First, Then Build
Claude Code provides two operating modes. Always start in Plan Mode. Only switch to Build Mode after the specification is reviewed and approved.
5.1 — Plan Mode (use Claude Opus 5)
Plan Mode is read-only: the agent analyzes, designs, and proposes — but does not modify files.
- Recommended model:
claude-opus-5(highest reasoning quality) - When to use: ALWAYS at the start of a task, with or without Spec Kit
- Goal: Produce a clear, reviewed specification or implementation plan
Enter Plan Mode in Claude Code:
Press Shift+Tab to cycle into plan mode, or start Claude Code with the flag:
claude --permission-mode planSelect the model:
/model claude-opus-5Now describe what you want to build. Review the result carefully:
- Does it match your intent?
- Are all entities, connectors, business objects correctly identified?
- Are edge cases covered?
- Do external requirements (Excel/PDF/Jira) trace 1:1 into the spec?
5.2 — Build Mode (use Claude Sonnet 5)
Once the specification or plan is good, switch to Build Mode for the actual implementation. Sonnet is faster and cheaper, and is fully sufficient for executing a well-defined plan.
- Recommended model:
claude-sonnet-5(cost-efficient, fast) - When to use: ONLY after the plan/spec is reviewed and approved
Switch to Build Mode:
Press Shift+Tab again to leave plan mode (back to default/accept-edits mode).
Select the model:
/model claude-sonnet-5Now instruct the agent to execute the approved plan. It will create files, run commands, and commit changes.
Step 6 — Sync Dependencies, Install and Deploy
Before pushing, run /sync-dependencies so the Simplifier transport picks up the referenced connectors and business objects. Use Install to install dependencies; after Deploy the app runs on Simplifier.
Step 7 — (Optional, Recommended for Larger Projects) Integrate GitHub Spec Kit
For larger applications, we strongly recommend using the GitHub Spec Kit framework. Spec Kit drives Spec-Driven Development: you first write a precise specification, then let the agent implement it.
Run
/init-simplifier(Step 4) and enter Plan Mode (Step 5) BEFORE Spec Kit commands.
7.1 — Install the Specify CLI (one-time, system-wide)
Spec Kit ships as the specify CLI. Install once via uv (recommended) or pipx:
# Recommended — using uv
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# Alternative — using pipx
pipx install git+https://github.com/github/spec-kit.gitVerify:
specify version
specify checkIf
command not found: uv→ install uv first, or use thepipxline above.
7.2 — Initialize Spec Kit in your project
From inside your project directory (the Simplifier Git clone from Step 2):
cd ~/simplifier-projects/<your-app-name>
# Initialize in the current folder for Claude Code
specify init . --integration claude
# or, equivalent
specify init --here --integration claudeThis creates the .specify/ folder with templates, plus Claude Code slash commands under .claude/commands/.
7.3 — Establish project principles (constitution)
In Claude Code, run:
/speckit.constitution Create principles focused on code quality, Simplifier best practices, BusinessObject testing, naming conventions for connectors, and UI consistency for SAPUI5/Fiori screens.7.4 — Create the specification
For a small/internal project, write the spec directly:
/speckit.specify Build a Simplifier app that lets warehouse managers scan barcodes, look up stock levels via the SAP RFC connector, and post goods movements. The UI is a Fiori list-detail layout.7.4.a — Integrate external requirements (Excel, Word, PDF, Jira export)
If you already have requirements in an Excel sheet with user stories, a Word/PDF specification, a Jira export, or any other external document, do not retype them. Drop the file(s) into the project folder (e.g. into a docs/ subfolder) and let Claude Code read them.
mkdir docs
cp ~/Downloads/UserStories.xlsx docs/
cp ~/Downloads/RequirementsSpec.pdf docs/Then in Claude Code (Plan Mode + Opus 5), use a prompt like:
Prompt example — Excel with user stories:
Read the file docs/UserStories.xlsx. Each row is a user story with columns:
ID, Role, Goal, Reason (As a / I want / So that), Acceptance Criteria, Priority, Epic.
Consolidate the stories into a coherent specification grouped by Epic.
Identify all entities, Simplifier Connectors, BusinessObjects and screens implied
by the stories. Then call /speckit.specify with the consolidated text so that
spec.md is created. Preserve the original Story IDs as references in the spec
so we can trace every requirement back to the Excel.Prompt example — PDF / Word specification:
Read docs/RequirementsSpec.pdf. Extract:
- functional requirements (numbered FR-x)
- non-functional requirements (NFR-x)
- data entities and their fields
- external systems / integrations
Then run /speckit.specify with a structured summary that keeps the FR/NFR IDs
as traceability anchors. Flag anything ambiguous and ask me before finalizing.Prompt example — Jira / Azure DevOps CSV export:
Read docs/jira-export.csv. Each row is an issue (Story or Task) with key,
summary, description, acceptance criteria, labels, epic link.
Group by Epic Link, deduplicate, and produce a single spec input. Then call
/speckit.specify. Keep Jira keys (e.g. PROJ-123) as references next to each
requirement so we can sync back to Jira later.Claude Code can read
.xlsx,.csv,.docx,.md,.txtdirectly. For very large files, ask the agent to summarize chapter by chapter first, then produce the consolidated spec.
After /speckit.specify has run, review spec.md and refine with /speckit.clarify if anything is underspecified.
7.5 — Plan, break down, implement
/speckit.plan Use the Simplifier platform: REST/SAP-RFC connectors, server-side BusinessObjects for business logic, and a Fiori-style SAPUI5 frontend. Persist app artifacts via the Simplifier Git integration.
/speckit.tasks
/speckit.analyze # optional — cross-artifact consistency check before implement
/speckit.implement/speckit.constitution |
Project-wide guiding principles |
/speckit.specify |
Define what to build (functional spec) |
/speckit.clarify |
Resolve underspecified areas (run before /speckit.plan) |
/speckit.plan |
Define how to build it (tech stack, architecture) |
/speckit.tasks |
Generate the actionable task list |
/speckit.analyze |
Cross-artifact consistency & coverage check |
/speckit.implement |
Execute all tasks |
Recommended Workflow Summary
| Step | Action | Model | Mode |
|---|---|---|---|
| 1 | Create project directory | — | — |
| 2 | git clone from Simplifier App Editor |
— | — |
| 3 | Add MCPs via claude mcp add (Simplifier, Fiori, UI5, Playwright) |
— | — |
| 4 | Run /init-simplifier |
— | — |
| 5 | Enter Plan Mode + select Opus 5 | Opus 5 | Plan |
| 6 | Run /sync-dependencies → Install → Deploy |
Sonnet 5 | Build |
| 7 | (Large projects) specify init + /speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan |
Opus 5 | Plan |
| 8 | Review and approve plan + spec | Opus 5 | Plan |
| 9 | Switch to Build Mode + Sonnet 4.5; /speckit.tasks → /speckit.analyze → /speckit.implement |
Sonnet 5 | Build |
| 10 | Commit and push to Simplifier Git | Sonnet 5 | Build |
Tips & Best Practices
- One project = one folder = one set of MCPs. Never share MCP configs across unrelated apps.
- Always start in Plan Mode. The cost of a bad plan is far higher than the cost of Opus tokens.
- Switch to Sonnet for execution. Building from a clear plan does not require Opus-level reasoning.
- Refresh your Simplifier Token after every login. Remove and re-add the
simplifierMCP — otherwise calls will fail with auth errors. - Drop external requirements into
docs/. Excel, PDF, Word, CSV — let the agent read them; never copy-paste content by hand. - Preserve external IDs. Story IDs (Jira keys, Excel row IDs, FR-/NFR- numbers) belong in the spec for traceability.
- Commit often. Use the cloned Simplifier Git repository as your source of truth — push back to the App Editor when work is done.
- Use Spec Kit for anything non-trivial. Even a single
spec.mddramatically improves agent output. - Keep MCPs up to date. Re-run
claude mcp listperiodically to check connectivity.
Troubleshooting
| Symptom | Fix |
|---|---|
claude mcp list shows MCP as disconnected |
Re-run the claude mcp add command; check network/proxy |
| Simplifier MCP shows auth / 401 error | Your SIMPLIFIER_TOKEN expired after re-login → claude mcp remove simplifier and add again with the new token |
| Simplifier MCP opens an error page in browser on startup | Read the page — it details the connection issue (wrong URL, invalid token, network) and how to fix it |
| Agent does not know about Simplifier APIs | Confirm simplifier is added in the current project folder, not globally |
| Agent edits files in Plan Mode | You are not in Plan Mode — press Shift+Tab until the bottom bar shows plan mode on |
| Opus 4.5 too slow / too expensive for small edits | Switch to Sonnet 4.5 with /model claude-sonnet-5 after the plan is locked |
| Playwright MCP fails to launch browser | Run npx playwright install once to install browser binaries |
specify: command not found |
Install via uv tool install specify-cli --from git+https://github.com/github/spec-kit.git (or pipx) |
/speckit.* commands not visible in Claude Code |
Re-run specify init . --integration claude inside the project folder, then restart Claude Code |
| Excel/PDF requirements ignored by agent | Place files in docs/ and explicitly reference the path in your prompt (e.g. docs/UserStories.xlsx) |
