AI Integration

MCP server for Claude Code, Cursor, and any MCP-aware agent. Audit, migrate, and manage images from chat.

AuraImage ships an MCP server that turns image work into a few-word prompt. Add the server once, and your agent can audit a codebase for unoptimized images, upload them, rewrite your JSX to use <AuraImage />, generate alt text, and preview smart-crop variants — all without you writing upload code.

Setup

Claude Code / Cursor (project-scoped)

Create or edit .mcp.json in your project root:

.mcp.json

{
  "mcpServers": {
    "auraimage": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@auraimage/mcp-server@latest"],
      "env": {
        "AURA_SECRET_KEY": "${AURA_SECRET_KEY}"
      }
    }
  }
}

Restart your agent so the MCP server loads. The ${AURA_SECRET_KEY} form picks up the value from your shell / .env.local — keep the secret out of .mcp.json so the file is safe to commit.

Claude Desktop (global)

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "auraimage": {
      "command": "npx",
      "args": ["-y", "@auraimage/mcp-server@latest"],
      "env": {
        "AURA_SECRET_KEY": "sk_live_..."
      }
    }
  }
}

Required env

Variable	Required for	Notes
`AURA_SECRET_KEY`	`migrate_assets`	Used to mint upload signatures.
`AURA_CDN_URL`	optional	Override the CDN base URL (defaults to `https://cdn.auraimage.ai`). Useful for self-hosted or staging.
`AURA_API_URL`	optional	Override the API base URL.

The project name is not an env var — it's passed as a tool argument so one MCP server can operate across multiple projects in the same session.

Tell your agent

"Install AuraImage in this project."

The agent reads your codebase, picks the right framework recipe, prompts for the keys it needs, writes .env.local, installs @auraimage/sdk, scaffolds the upload-token route, and adds the registry components. One confirmation, idempotent, stops cleanly on failure.

After install you can ask:

"Audit this project for unoptimized images." "Migrate everything in /public to AuraImage." "Generate alt text for the images on the landing page." "Show me 1:1 crop variants of team-photo.jpg."

Available tools

`audit_lcp`

Scans a project directory for unoptimized <img> tags and local image assets, and estimates LCP savings if you migrated to AuraImage.

Argument	Type	Notes
`directory`	`string`	Absolute path to the project root.

Returns a plain-text report: total unoptimized images, total bytes, estimated LCP improvement, and the list of files (truncated at 20 with a "... and N more" tail).

`migrate_assets`

Uploads local images, then rewrites the surrounding JSX/TSX to use <AuraImage /> with the correct src, width, and height.

Argument	Type	Default	Notes
`directory`	`string`	required	Directory containing images.
`projectName`	`string`	required	Your AuraImage project name.
`dryRun`	`boolean`	`false`	When `true`, lists what would happen without uploading or rewriting.

Refuses to operate on system directories (/etc, /root, /sys, /proc, /boot, /dev).

`generate_alt`

Generates accessible alt text for an image URL using vision AI.

Argument	Type	Notes
`imageUrl`	`string`	Any reachable image URL.

Returns a single sentence of alt text suitable for direct use.

`generate_responsive_tag`

Generates a complete <picture> element with AVIF + WebP srcSets and a JPEG fallback.

Argument	Type	Default	Notes
`projectName`	`string`	required
`filename`	`string`	required	The `key` returned by upload.
`widths`	`number[]`	`[400, 800, 1200]`	Widths to emit in `srcSet`.
`alt`	`string`	`""`	Optional alt text.

Sample output:

<picture>
  <source
    type="image/avif"
    srcSet="https://cdn.auraimage.ai/my-app/hero.jpg?w=400&fmt=avif 400w,
      https://cdn.auraimage.ai/my-app/hero.jpg?w=800&fmt=avif 800w,
      https://cdn.auraimage.ai/my-app/hero.jpg?w=1200&fmt=avif 1200w"
  />
  <source
    type="image/webp"
    srcSet="https://cdn.auraimage.ai/my-app/hero.jpg?w=400&fmt=webp 400w,
      https://cdn.auraimage.ai/my-app/hero.jpg?w=800&fmt=webp 800w,
      https://cdn.auraimage.ai/my-app/hero.jpg?w=1200&fmt=webp 1200w"
  />
  <img
    src="https://cdn.auraimage.ai/my-app/hero.jpg?w=1200"
    alt="Golden Gate Bridge at sunset"
    width={1200}
    loading="lazy"
  />
</picture>

`smart_crop_preview`

Returns a list of CDN URLs for an image at a given size, one per smart-crop mode (face, auto, centered cover). Drop them into the chat to compare.

Argument	Type	Notes
`projectName`	`string`
`filename`	`string`
`width`	`number`	Output width.
`height`	`number`	Output height.

Recommended `CLAUDE.md` snippet

Pin AuraImage in your project's CLAUDE.md so every agent session has context:

## Image handling

This project uses AuraImage for image upload and delivery.
- MCP server: @auraimage/mcp-server (configured in .mcp.json)
- Project name: my-app
- Components: <AuraImage /> from @/components/aura/image,
  <AuraUploader /> from @/components/aura/uploader
- Use migrate_assets to move any local /public images to AuraImage
  before adding new <img> tags.

On this page