AI Integration

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. Pre-built agent skills sit one layer above: the MCP server gives your agent the tools, skills give it the judgment to use them correctly.

Setup

Every agent reads MCP config from a different file, in a different shape, with a different way of handling your secret key. Pick yours below, then restart the agent so the server loads.

Claude Code

Claude Code reads .mcp.json at the project root, and the ${AURA_SECRET_KEY} form resolves from your shell or .env.local so the file stays safe to commit. The full block, the one-line claude mcp add equivalent, and where repo conventions go in CLAUDE.md are on the Claude Code image CDN page.

Cursor

Cursor reads .cursor/mcp.json at the project root, or ~/.cursor/mcp.json globally — not .mcp.json. Full setup, including the ${env:...} secret form Cursor documents for this field, is on the Cursor image CDN page.

Codex

Codex keeps MCP servers in ~/.codex/config.toml under an [mcp_servers.auraimage] table — TOML rather than JSON, and global to every project on the machine. env_vars lists variable names only, so the key stays in your shell; the four-line block is on the Codex image CDN page.

GitHub Copilot

GitHub Copilot takes two configs: .vscode/mcp.json for the editor, which uses a servers key plus an inputs block for the key, and .github/mcp.json for Copilot CLI, which uses mcpServers. The CLI does not read the editor's file, so teams on both surfaces commit both — each config is on the GitHub Copilot image CDN page.

Gemini CLI

Gemini CLI reads .gemini/settings.json and expands shell-style variables in env, so a bare $AURA_SECRET_KEY resolves at launch and the committed file holds a variable name. gemini mcp add writes the block for you — the command and the JSON are both on the Gemini CLI image CDN page.

Cline

The Cline CLI reads ~/.cline/mcp.json, and the VS Code extension keeps the same JSON in cline_mcp_settings.json, reached from the Cline panel rather than by path. Cline documents no environment-variable expansion here, so the key stays blank in the config and lives in the environment instead — the safe setup is on the Cline image CDN page.

Grok Build

Grok Build takes TOML like Codex, but project-scoped in .grok/config.toml, with env vars in their own [mcp_servers.auraimage.env] table. It expands ${AURA_SECRET_KEY} there, so the file stays safe to commit — the block and the grok mcp doctor check are on the Grok Build image CDN page.

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

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.

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.

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

The migration guide walks through this tool alongside the script-based routes from Cloudinary, S3/R2, and any other CDN.

generate_alt

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

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.

Sample output:

<picture>
  <source
    type="image/avif"
    srcSet="https://cdn.auraimage.ai/my-app/w=400/hero.avif 400w,
      https://cdn.auraimage.ai/my-app/w=800/hero.avif 800w,
      https://cdn.auraimage.ai/my-app/w=1200/hero.avif 1200w"
  />
  <source
    type="image/webp"
    srcSet="https://cdn.auraimage.ai/my-app/w=400/hero.webp 400w,
      https://cdn.auraimage.ai/my-app/w=800/hero.webp 800w,
      https://cdn.auraimage.ai/my-app/w=1200/hero.webp 1200w"
  />
  <img
    src="https://cdn.auraimage.ai/my-app/w=1200/hero"
    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.

Recommended CLAUDE.md snippet (Claude Code)

Pin AuraImage in your project's CLAUDE.md so every Claude Code session has context. On another agent, put the same text in its own rules file — .cursor/rules/*.mdc, AGENTS.md, .github/copilot-instructions.md, GEMINI.md, .clinerules/, or .grok/rules/ — and swap .mcp.json for that agent's config path:

## 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.