# BLUEPRINT: StackApps MCP Gateway [x402]
# Version: 1.3.0
# URL: https://mcp.stackapps.app
# Updated: 2026-07-04

## IDENTITY
name: StackApps MCP Gateway
description: Unified x402 gateway for the StackApps tool suite. Pay per call in USDC
  on Base mainnet — no account required to start; first x402 payment may issue a temp
  API key (first payment only). Each member app (Imagcon today; StackBill, StackSlip,
  and others as they ship) contributes tools here. One server, one install, the full suite.
category: developer-tools
contact: support@stackapps.app

## SUMMARY
tagline: One server. All StackApps tools. Pay per call in USDC.
audience: AI agents and developers who need StackApps suite tools without creating an
  account. Requires an EVM wallet funded with USDC on Base mainnet (eip155:8453).
capabilities:
  - create-pwa-icons-from-image: Upload image → full PWA icon set (27 files + manifest.json) — $0.10 USDC
  - create-splash-screens-from-image: Upload image → 16 iOS/iPad splash screens — $0.10 USDC
  - generate-pwa-icons: Text prompt → AI-generated PWA icon set — $0.295 USDC
  - generate-image: Text prompt → AI-generated source image (image_key + preview URL) — $0.195 USDC
  - generate-splash-screens: Text prompt → AI-generated 16 iOS/iPad splash screens — $0.295 USDC
  - get-wallet-profile: Look up temp vs permanent wallet profile — free
  - setup-wallet-profile: Activate permanent account from first-payment profile token — free

## AUTH
provider: none
payment: x402 — EVM wallet, USDC on Base mainnet (eip155:8453)
note: No Firebase account or API key required to start. Each tool call settles independently
  on-chain via EIP-3009. The MCP server signs payment authorizations with the
  configured wallet and retries automatically — no user interaction needed per call.

## WALLET PROFILE
note: On every first payment from a new wallet, Imagcon auto-creates a 60-day
  temporary account linked to that wallet address. No action required.
headers-on-first-payment:
  - X-Imagcon-Token: profile token (tok_...) — stored in session only, never echoed in tool text
  - X-Imagcon-Profile-Setup: activate URL (non-secret) — first payment only
  - X-Imagcon-Api-Key: Imagcon API key — first payment only; unlocks all 14 imagcon-mcp tools
surfaced-by: stackapps-suite-mcp appends a non-secret opt-in message to tool results on
  first payment only (when X-Imagcon-Profile-Setup is present). Secrets stay in session
  memory — never in chat logs. Example: "A 60-day temp account was created for your wallet.
  To keep it permanently (free), call setup_wallet_profile with the profile token from
  secure storage, or visit the activate URL. An Imagcon API key was issued — use imagcon-mcp
  with that key (store securely, not in chat)."
activate-endpoint: POST https://imagcon.app/routes/x402/profile/activate
  body: { "profile_token": "tok_...", "wallet_address": "0x...", "name": "...",
    "terms_confirmed": true, "signature": "0x...", "message": "imagcon.app/profile/activate:tok_...:<unix_ts>" }
  signature: EIP-191 personal_sign over the message, signed with the paying wallet
    key — stackapps-suite-mcp signs automatically; no agent input required.
    Server verifies the recovered address matches wallet_address (±300s window).
  terms: https://imagcon.app/terms-of-service
  note: stackapps-suite-mcp derives wallet_address from WALLET_PRIVATE_KEY automatically;
    agents pass name and terms_confirmed to setup_wallet_profile. profile_token defaults
    to the session token from the first paid call if omitted.
paper-plan: If setup_wallet_profile is never called, the temp account auto-deletes
  after 60 days. Next payment from same wallet starts a fresh 60-day window.

## MCP
server: stackapps-suite-mcp
preferred-transport: stdio
http-transport: discovery only — https://mcp.stackapps.app serves blueprint.txt; paid tools
  require local stdio with WALLET_PRIVATE_KEY. Do not use HTTP MCP on Cloud Run.
install: claude mcp add stackapps-suite -- uvx stackapps-suite-mcp --wallet-key 0x...
package: stackapps-suite-mcp on PyPI
fallback-wheel: https://stackapps.app/downloads/stackapps_suite_mcp-0.1.5-py3-none-any.whl
requirements: uv/uvx installed (https://docs.astral.sh/uv/). Python 3.11–3.12.
  EVM wallet private key. USDC on Base mainnet in that wallet.

### TRANSPORT (stdio)
command: uvx stackapps-suite-mcp --wallet-key 0x...
note: Runs as a local stdio process. Use WALLET_PRIVATE_KEY env var rather than
  passing the key on the command line.

### MCP TOOLS
server: stackapps-suite-mcp

create_pwa_icons_from_image | image_path, output_dir | Full PWA icon set (27 files + manifest.json) from PNG/JPEG/WebP ($0.10 USDC) | source: imagcon.app
create_splash_screens_from_image | image_path, background_color, output_dir | 16 iOS/iPad splash screens from PNG/JPEG/WebP ($0.10 USDC) | source: imagcon.app
generate_pwa_icons | description, output_dir | AI-generate PWA icon set from text prompt ($0.295 USDC) | source: imagcon.app
generate_image | description | AI-generate source image, returns image_key + preview_url ($0.195 USDC) | source: imagcon.app
generate_splash_screens | description, background_color, output_dir | AI-generate 16 iOS/iPad splash screens ($0.295 USDC) | source: imagcon.app
get_wallet_profile | (none) | Look up temp vs permanent wallet profile (free) | source: imagcon.app
setup_wallet_profile | name, terms_confirmed, profile_token, company_name, tax_id | Activate permanent account from first-payment profile token (free) | source: imagcon.app

### PAYMENTS
network: Base mainnet (eip155:8453)
asset: USDC
mechanism: x402 (HTTP 402 / EIP-3009)
flow: Each tool call makes an HTTP request to the source app's x402 endpoint. The
  server receives a 402 challenge, signs a payment authorization with the configured
  wallet, and retries. Settlement is on-chain; funds go directly to the source app's
  wallet. StackApps takes no cut.
prices:
  - $0.10 USDC: create_pwa_icons_from_image, create_splash_screens_from_image
  - $0.195 USDC: generate_image
  - $0.295 USDC: generate_pwa_icons, generate_splash_screens
  - free: get_wallet_profile, setup_wallet_profile (no x402 charge)
client-safety: The server refuses to sign any payment challenge that does not pay
  the StackApps suite wallet, or that exceeds the per-call cap ($0.50 USDC by
  default; override with STACKAPPS_MAX_USD_PER_CALL). A compromised or spoofed
  endpoint cannot redirect or inflate payments.

### REQUIRED-SECRETS
- WALLET_PRIVATE_KEY:
    description: EVM wallet private key for signing x402 payment authorizations
    format: 0x-prefixed hex string (64 hex chars after 0x)
    funding: Wallet must hold USDC on Base mainnet.
    storage:
      shell: export WALLET_PRIVATE_KEY=0x... in ~/.zshrc or ~/.bashrc
      claude-code: pass via --wallet-key argument in claude mcp add command
    warning: never commit the raw key to git; never set on Cloud Run
- IMAGCON_PROFILE_TOKEN:
    description: Optional override for X-Imagcon-Token header on subsequent x402 calls
    format: tok_... string from Imagcon first-payment response
    note: Normally stored in session memory automatically after first paid call

### CLIENT-CONFIGS

#### Claude Code (CLI)
claude mcp add stackapps-suite -- uvx stackapps-suite-mcp --wallet-key 0x...

#### Claude Code / Cursor / Windsurf / Cline (JSON)
{
  "mcpServers": {
    "stackapps-suite": {
      "command": "uvx",
      "args": ["stackapps-suite-mcp", "--wallet-key", "0x..."]
    }
  }
}

## ACCESS
preferred: mcp

## CAPABILITY: create-pwa-icons-from-image
description: Generate a full PWA icon set from an existing local image file.
  Produces 27 files covering all required PWA, iOS, Android, Windows tile, and
  Safari pinned-tab sizes, plus manifest.json, packaged as a ZIP and extracted
  to output_dir. No AI generation — source image is uploaded directly.
  Powered by Imagcon (imagcon.app).
input:
  - name: image_path
    type: string
    required: true
    description: Absolute path to a PNG, JPEG, or WebP file on the local machine.
  - name: output_dir
    type: string
    required: false
    default: ./public/icons
    description: Directory where the ZIP is extracted. Relative paths resolve
      against the MCP server process directory.
output:
  - type: file
    description: ZIP extracted to output_dir. Contains icons/ subdirectory and manifest.json.
auth-required: false
payment: $0.10 USDC per call (Base mainnet, x402)
source: imagcon.app/routes/x402/icons-from-image

### MCP
tool: create_pwa_icons_from_image

## CAPABILITY: create-splash-screens-from-image
description: Generate 16 iOS and iPad launch splash screens from an existing local
  image file. Covers all current iPhone and iPad canvas sizes. Output is a ZIP
  of flat PNG files extracted to output_dir. No AI generation — source image is
  uploaded directly. Powered by Imagcon (imagcon.app).
input:
  - name: image_path
    type: string
    required: true
    description: Absolute path to a PNG, JPEG, or WebP file on the local machine.
  - name: background_color
    type: string
    required: false
    default: "#ffffff"
    description: Hex color string for the splash screen background (e.g. #1a1a2e).
  - name: output_dir
    type: string
    required: false
    default: ./public/splash
    description: Directory where the ZIP is extracted.
output:
  - type: file
    description: ZIP extracted to output_dir. Contains 16 flat PNG splash screens.
auth-required: false
payment: $0.10 USDC per call (Base mainnet, x402)
source: imagcon.app/routes/x402/splash-from-image

### MCP
tool: create_splash_screens_from_image

## CAPABILITY: generate-pwa-icons
description: AI-generate a complete PWA icon set from a text description of your app.
  Imagcon generates a source image from the prompt, then produces all 27 PWA icon
  sizes plus manifest.json, packaged as a ZIP extracted to output_dir.
  Powered by Imagcon (imagcon.app).
input:
  - name: description
    type: string
    required: true
    description: Text description of the app — used as the AI image generation prompt.
      Be specific about colors, style, and subject matter.
  - name: output_dir
    type: string
    required: false
    default: ./public/icons
    description: Directory where the ZIP is extracted.
output:
  - type: file
    description: ZIP extracted to output_dir. Contains AI-generated source image,
      icons/ subdirectory, and manifest.json.
auth-required: false
payment: $0.295 USDC per call (Base mainnet, x402)
source: imagcon.app/routes/x402/generate-pwa-icons

### MCP
tool: generate_pwa_icons

## CAPABILITY: generate-image
description: AI-generate a source image from a text description. Returns image_key
  and a preview URL. Use this when you want to review the generated image before
  committing to a full icon set generation. Powered by Imagcon (imagcon.app).
input:
  - name: description
    type: string
    required: true
    description: Text description used as the AI image generation prompt.
output:
  - type: json
    description: image_key (string) and preview_url (string). The image_key can
      be passed to Imagcon's create_icons_from_key tool (via imagcon-mcp) to
      generate the full icon set without regenerating the image.
auth-required: false
payment: $0.195 USDC per call (Base mainnet, x402)
source: imagcon.app/routes/x402/generate-image

### MCP
tool: generate_image

## CAPABILITY: generate-splash-screens
description: AI-generate 16 iOS and iPad launch splash screens from a text description
  of your app. Imagcon generates a source image from the prompt, then produces all
  splash screen canvas sizes, packaged as a ZIP extracted to output_dir.
  Powered by Imagcon (imagcon.app).
input:
  - name: description
    type: string
    required: true
    description: Text description used as the AI image generation prompt.
  - name: background_color
    type: string
    required: false
    default: "#ffffff"
    description: Hex color string for the splash screen background.
  - name: output_dir
    type: string
    required: false
    default: ./public/splash
    description: Directory where the ZIP is extracted.
output:
  - type: file
    description: ZIP extracted to output_dir. Contains AI-generated source image
      and 16 flat PNG splash screens.
auth-required: false
payment: $0.295 USDC per call (Base mainnet, x402)
source: imagcon.app/routes/x402/generate-splash-screens

### MCP
tool: generate_splash_screens

## CAPABILITY: get-wallet-profile
description: Look up the Imagcon wallet profile for the configured wallet address.
  Use before prompting the user to activate — shows temp vs permanent status.
input: []
output:
  - type: string
    description: Profile status and optional display name.
auth-required: false
payment: free (no x402 charge)
source: imagcon.app/routes/x402/profile/{wallet}

### MCP
tool: get_wallet_profile

## CAPABILITY: setup-wallet-profile
description: Activate a permanent Imagcon account linked to your wallet. Call this
  after the first x402 payment. profile_token is stored in session memory after the
  first paid call; pass explicitly from secure storage if needed. Permanent accounts
  keep payment history indefinitely. Without activation the temp account auto-deletes
  after 60 days (paper plan).
input:
  - name: name
    type: string
    required: true
    description: Display name for the profile (person or business name).
  - name: terms_confirmed
    type: boolean
    required: true
    description: Must be true only after the human has read https://imagcon.app/terms-of-service and agreed.
  - name: profile_token
    type: string
    required: false
    description: tok_... token from first x402 payment. Defaults to session token if omitted.
  - name: wallet_address
    type: string
    required: true
    description: Derived from WALLET_PRIVATE_KEY by stackapps-suite-mcp (not an agent input).
  - name: company_name
    type: string
    required: false
    description: Optional business name.
  - name: tax_id
    type: string
    required: false
    description: Optional tax ID / VAT number.
output:
  - type: string
    description: Confirmation message with account status.
auth-required: false
payment: free (no x402 charge)
source: imagcon.app/routes/x402/profile/activate

### MCP
tool: setup_wallet_profile

## SUITE
note: This gateway grows as member apps ship x402 endpoints. Each new capability
  will appear in ## MCP TOOLS above and as a ## CAPABILITY block below.
  The install command and server URL do not change — agents with stackapps-suite-mcp
  already installed receive new tools automatically on next connect.
members:
  - imagcon.app — PWA icons, splash screens, AI image generation (live)
  - stackbill.app — invoicing (planned)
  - stackslip.app — packing slips (planned)