# AI Integration (https://auraimage.ai/docs/ai-integration)



AuraImage ships an [MCP server](https://modelcontextprotocol.io) 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](/docs/skills) sit one layer above: the MCP server gives your agent the tools, skills give it the judgment to use them correctly.

## Setup [#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]

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](/claude-code).

### Cursor [#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](/cursor).

### Codex [#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](/codex).

### GitHub Copilot [#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](/github-copilot).

### Gemini CLI [#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](/gemini-cli).

### Cline [#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](/cline).

### Grok Build [#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](/grok-build).

### Claude Desktop (global) [#claude-desktop-global]

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

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

### Required env [#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 [#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 [#available-tools]

### `audit_lcp` [#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` [#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`).

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

***

### `generate_alt` [#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` [#generate_responsive_tag]

Generates a complete `<picture>` element with AVIF + WebP `srcSet`s and a JPEG fallback.

| Argument      | Type       | Default            | Notes                                             |
| ------------- | ---------- | ------------------ | ------------------------------------------------- |
| `projectName` | `string`   | required           |                                                   |
| `name`        | `string`   | required           | The extension-less image name returned by upload. |
| `widths`      | `number[]` | `[400, 800, 1200]` | Widths to emit in `srcSet`.                       |
| `alt`         | `string`   | `""`               | Optional alt text.                                |

Sample output:

```tsx
<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` [#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` |                                |
| `name`        | `string` | The extension-less image name. |
| `width`       | `number` | Output width.                  |
| `height`      | `number` | Output height.                 |

## Recommended `CLAUDE.md` snippet (Claude Code) [#recommended-claudemd-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:

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


## Related

- [Agent Skills](https://auraimage.ai/docs/skills)
- [Agent Skills](https://auraimage.ai/skills)
- [Image CDN for Claude Code](https://auraimage.ai/claude-code)
- [Image CDN for Cursor](https://auraimage.ai/cursor)
- [How We Built an AI Agent That Configures Your Image CDN — 5 Lessons From Shipping the AuraImage MCP Server](https://auraimage.ai/blog/building-ai-agent-for-image-cdn)