AppStaged · Guide

Agents & MCP

Connect Claude Code or Codex and create screenshots through conversation.

On this page

Connect your account to an AI coding client, then ask it to build, adjust, and render a screenshot set. Your sets remain editable in the AppStaged editor.

Connect your client

Install Claude Code or Codex first, then choose its setup below. Commands are for bash or zsh. You need a AppStaged API key; your Claude or OpenAI key is a different credential.

1. Connect AppStaged to Claude Code

Create a key in Settings → Developer. Set these two variables in your terminal. They connect both MCP and local screenshot uploads to the same account. Replace the key placeholder with your key.

Terminal · bash / zsh

export APPSTAGED_API_KEY="YOUR_APPSTAGED_API_KEY"
export APPSTAGED_MCP_URL="https://appstaged.com/api/mcp"

Terminal · bash / zsh

claude mcp add --transport http appstaged \
  "$APPSTAGED_MCP_URL" \
  --header "Authorization: Bearer $APPSTAGED_API_KEY"

The command saves the expanded key in Claude’s MCP configuration; file uploads also need both variables in Claude’s shell. The config-file option references the key environment variable. Launch your agent from this terminal after installing the skill. Set both variables again in new terminals; an already-running agent will not inherit later exports. Desktop clients need both variables in their launch environment.

Open a new session and run /mcp to check the connection. Claude Code reference ↗

2. Install the AppStaged skill

The skill includes a local-file upload helper: your agent can upload screenshots from disk without copying base64 into chat, then design, review, and export the set. Run this once in your terminal; the installer puts it in the right folder for your client.

Terminal · Node.js 20+ required

npx skills@1.5.23 add "https://appstaged.com/skills/appstaged.zip" --agent claude-code --global

Installs for your user account across projects. Review the installer’s prompts before confirming. Already installed? Running this again lets you update it.

Manual install or install for one project

Download the skill ZIP, unzip it, and place the appstaged folder in ~/.claude/skills/. Save personal edits before replacing an existing installation.

For a project installation, run the command from your project folder and omit --global.

3. Start a new agent session

Launch your agent from the terminal where you set both environment variables. Run /mcp, then send this prompt to check the skill, local uploads, and account allowances before creating anything.

Send to your agent

/appstaged
Read the AppStaged skill first. Check my MCP connection and call screenset_usage for my actual allowances. Verify the bundled scripts/upload.mjs helper and check that APPSTAGED_API_KEY and APPSTAGED_MCP_URL are set in your shell without printing their values. Resolve missing upload setup before creating a set. List my existing apps and screenshot sets, then help me design a store listing using my real screenshots. Use the helper for local-file uploads and show previews before exporting.

MCP connects your account; the skill adds workflow and design guidance. Completing one step does not automatically complete the other.

Connection and skill, together

The setup above covers both parts: connecting your account through MCP and installing the AppStaged workflow and design skill. Choose your client to get its copyable commands and starter prompt. The skill installer downloads directly from this deployment; no GitHub access or manual folder setup is needed.

Use the same setup in Settings → Developer, alongside API key creation and connection testing. Manual ZIP installation remains available under the skill step. If you use a different Agent Skills client, download the portable package and follow that client's installation instructions.

Try your first request

Start with a small brief. Tell your agent the app, audience, screenshot size, and visual direction. For example:

text

Use AppStaged to create a three-screen App Store set
for a running app called Pace.

Use a warm cream background, dark olive text, and lime accents.
Start with these headlines:
1. Find your everyday pace
2. A little further, every week
3. Your progress, in perspective

Show me a preview before exporting. Ask me for my app screenshots
before adding any screenshot assets.

Your agent can inspect available presets and templates with screenset_capabilities, create a set, apply edits, upload assets, and render a preview. Opening that set in the editor lets you refine it manually.

Review before publishing

Store publishing replaces existing screenshots in the selected size and locale. Ask your agent to show the target app, size, locale, and preview before confirming publication. See Publishing to stores for connection setup and limits.

Troubleshoot a connection

Unauthorized / 401: check that the key is valid, has not been revoked, and belongs to the same AppStaged deployment as the endpoint.
Missing environment variable: set both APPSTAGED_API_KEY and APPSTAGED_MCP_URL in the terminal that launches the client, then restart it. MCP can be connected while the local upload helper is missing these variables.
OAuth login appears: AppStaged currently uses a Bearer API key. Use the command or configuration above instead of an OAuth login command.
Local screenshots / base64 too large: use the skill’s scripts/upload.mjs helper. It reads the file from disk and sends it directly to MCP without carrying base64 through chat. Requires Node.js 20+, shell access, and the two setup variables.
Revision conflict: ask the agent to fetch the latest set before applying another edit.

Create, test, rotate, or revoke credentials in Settings → Developer. Read more in API keys.