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

## 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). Member apps live today: Imagcon (icons, splash, AI
  images, resize, x402 validation) and StackBill (invoice PDFs). More as they ship.
  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
  - resize-image: Resize image to exact dimensions or social presets (OG, Twitter, Instagram...) — $0.02 USDC
  - validate-x402-endpoint: Pre-flight check any x402 endpoint with a real signed probe — $0.01 USDC
  - create-invoice: JSON in → professional invoice PDF out, server-side totals — $0.10 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.7-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
resize_image | image_path, output_path, preset, width, height, mode, focal, background_color, output_format, quality | Resize local image to exact dimensions or social preset ($0.02 USDC) | source: imagcon.app
validate_x402_endpoint | url, body | Real-payment probe of any x402 endpoint: facilitator verdict + lint + discovery ($0.01 USDC) | source: imagcon.app
create_invoice | recipient_name, recipient_address, line_items, output_path, sender_name, sender_address, invoice_number, due_date, tax_rate, notes, template | Professional invoice PDF, server-side totals, per-wallet auto-numbering ($0.10 USDC) | source: stackbill.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.01 USDC: validate_x402_endpoint
  - $0.02 USDC: resize_image
  - $0.10 USDC: create_pwa_icons_from_image, create_splash_screens_from_image, create_invoice
  - $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: resize-image
description: Resize a local image to exact dimensions or a social-media preset —
  Open Graph (1200x630), Twitter card, YouTube thumbnail, Instagram square/portrait/
  story, LinkedIn post, Twitter header, GitHub social. Fit modes avoid distortion:
  cover (focal-point crop), contain (padded), blur (letterbox fill — best for OG),
  stretch. 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_path
    type: string
    required: false
    default: ./resized.png
    description: Where the resized image is written.
  - name: preset
    type: string
    required: false
    description: Social preset (og, twitter-card, youtube-thumbnail, instagram-square,
      instagram-portrait, instagram-story, linkedin-post, twitter-header, github-social).
      Wins over width/height when provided.
  - name: width
    type: number
    required: false
    description: Target width in pixels (16-4096). Required with height when preset omitted.
  - name: height
    type: number
    required: false
    description: Target height in pixels (16-4096). Required with width when preset omitted.
  - name: mode
    type: string
    required: false
    default: cover
    description: Fit mode — cover, contain, blur, or stretch.
output:
  - type: file
    description: Resized image written to output_path (png/jpeg/webp).
auth-required: false
payment: $0.02 USDC per call (Base mainnet, x402)
source: imagcon.app/routes/x402/resize-image

### MCP
tool: resize_image

## CAPABILITY: validate-x402-endpoint
description: Pre-flight due diligence on any third-party x402 endpoint before spending
  real money on it. Sends a REAL signed payment from a fresh, unfunded, single-use
  wallet (by construction no funds can move) and returns the facilitator's verdict
  (healthy / broken / payment-ignored / not-x402 / unsupported-network), the decoded
  402 challenge, lint findings for silent payment-killers (e.g. resource descriptions
  over CDP's ~512-char cap), and a discovery report. Powered by Imagcon (imagcon.app).
input:
  - name: url
    type: string
    required: true
    description: The https x402 endpoint to probe. Must be publicly reachable on Base mainnet.
  - name: body
    type: object
    required: false
    description: JSON body the target endpoint expects on POST (default {}).
output:
  - type: json
    description: Validation report — verdict, challenge summary, lint, facilitator
      error verbatim if any, discovery report.
auth-required: false
payment: $0.01 USDC per call (Base mainnet, x402)
source: imagcon.app/routes/x402/validate

### MCP
tool: validate_x402_endpoint

## CAPABILITY: create-invoice
description: Generate a finished, professional invoice PDF from JSON — recipient and
  line items in, ready-to-send application/pdf out. Totals and tax are computed
  server-side so the numbers always add up. Templates: standard, legal (billing
  statement with matter dates), creative (service/fee layout). First payment
  auto-creates a wallet account (one-time X-StackApps-Token + API key in response
  headers, held in session memory); returning callers may omit invoice_number
  (sequential per-wallet numbering, e.g. INV-0001) and activated profiles may omit
  sender. Anonymous callers send everything, nothing is stored. USD only.
  Powered by StackBill (stackbill.app).
input:
  - name: recipient_name
    type: string
    required: true
    description: Who the invoice is billed to.
  - name: recipient_address
    type: string
    required: true
    description: Recipient postal address.
  - name: line_items
    type: array
    required: true
    description: At least one item, each {description, quantity, unitPrice}.
  - name: output_path
    type: string
    required: false
    default: ./invoice.pdf
    description: Where the PDF is written.
  - name: sender_name
    type: string
    required: false
    description: Who the invoice is from. Required for new/anonymous wallets.
  - name: sender_address
    type: string
    required: false
    description: Sender postal address. Required for new/anonymous wallets.
  - name: invoice_number
    type: string
    required: false
    description: Printed on the PDF. Omit on repeat calls for per-wallet auto-numbering.
  - name: due_date
    type: string
    required: false
    description: Due date, YYYY-MM-DD.
  - name: tax_rate
    type: number
    required: false
    description: Tax percent applied to the subtotal (e.g. 7.5).
  - name: notes
    type: string
    required: false
    description: Notes printed at the bottom of the invoice.
  - name: template
    type: string
    required: false
    default: standard
    description: PDF layout — standard, legal, or creative.
output:
  - type: file
    description: Invoice PDF written to output_path. Auto-assigned invoice number
      reported in the tool result when applicable.
auth-required: false
payment: $0.10 USDC per call (Base mainnet, x402)
source: stackbill.app/routes/x402/invoice-from-data

### MCP
tool: create_invoice

## 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, image resize,
    x402 endpoint validation (live)
  - stackbill.app — invoice PDF generation with per-wallet accounts (live)
  - stackslip.app — packing slips (planned)
