# Zegazone

> Zegazone is an AI-powered media collection platform. Store, organise, and share media collections. Bring your own AI agent.

## API

- [API Documentation](https://www.zegazone.com/api-docs): Full REST/MCP API reference
- [OpenAPI Spec](https://www.zegazone.com/openapi.json): Machine-readable API schema

## MCP connections

Two ways to connect — both expose identical tool sets (65 tools).

### Remote MCP (recommended)

No installation required. Add `https://mcp.zegazone.com/mcp` as a custom MCP connector in Claude.ai Cloud settings, or add `"url": "https://mcp.zegazone.com/mcp"` to your MCP config for Cursor remote mode. Complete browser OAuth when prompted.

### Local MCP (for developers)

For agents running on your local machine. Run `npx @zegazone_mcp/mcp@latest --pair`, complete the OAuth flow, and add the stdio config to your agent's MCP settings. Credentials are stored locally in `~/.zegazone-mcp/credentials.json`.

- [MCP Server on npm](https://www.npmjs.com/package/@zegazone_mcp/mcp): Install with `npx @zegazone_mcp/mcp@latest --pair`

## What agents can do

- Look up a single media item or collection by id (`media.get`, `collections.get`)
- Search media by keyword (`media.search`) or resolve share URLs (`collections.get_by_slug`)
- Create and manage media collections
- Upload and organise media items (images, video, audio, PDF, etc.)
- Search and browse public collections
- Manage collaborators and sharing
- Like, follow, and interact with public content
- Control the Zegazone UI (open collections, select media items)

## MCP quick start

### Remote (cloud agents)

Add `https://mcp.zegazone.com/mcp` as MCP connector URL. OAuth in browser.

### Local (stdio)

```bash
npx @zegazone_mcp/mcp@latest --pair
npx @zegazone_mcp/mcp@latest --version
```

Discover ops with MCP tools `operations_list` and `schema_get`. Use `@zegazone_mcp/mcp@latest` for typed schemas on all tools and lookup tools `media_get`, `collections_get`, `media_search`.

## Access control

All Zegazone MCP operations enforce the same access controls as the main application. You can only access collections and media that you own, are a collaborator on, or that are publicly shared. Attempting to access private resources belonging to other users will return 403.

## Image access for AI agents

Media files are stored in private R2 storage. The URLs returned by media.describe and media.list are proxy URLs that require Zegazone bearer auth — they are NOT fetchable by standard HTTP clients or AI tool fetch calls.

To visually analyse an image:
- Use media.analyse (server-side vision, returns AI description + suggested tags)
- Or use media.download_url to get a 5-minute proxied URL on api.zegaphone.com you can fetch

Do NOT attempt to fetch r2-proxy URLs directly — they will 401.

## Important: Claude Code / Claude Desktop bash sandbox restrictions

Claude's bash execution environment has a restricted network allowlist. Neither
*.r2.cloudflarestorage.com nor api.zegaphone.com are reachable from the bash sandbox.

To visually analyse images in Claude Code or Claude Desktop, use the artifact
(browser) context instead of bash — the artifact has full network access and can
fetch api.zegaphone.com download URLs without restriction.

Recommended workflow for Claude Code image enrichment:
1. Build a React artifact that fetches media.download_url for each image
2. Pass the returned URL to a vision API call within the artifact
3. Call media.update from the artifact with the results

Do NOT attempt to fetch image URLs from bash — use artifacts instead.

## Agent capability self-assessment

Zegazone prompt templates include self-assessment steps. Before attempting image-related
tasks, assess your own capabilities honestly:

Image generation:
- OpenClaw, GPT-4o, Gemini: can generate real PNG/JPEG images natively
- Claude Desktop, Claude.ai: can only produce SVG graphics, not raster images

Image analysis (vision):
- Most modern agents support vision — use media.download_url to get a fetchable URL
- If you cannot analyse images, fall back to filename and metadata

The prompts will guide you to the correct path based on your capabilities.
Always be honest about what you produced — note if a cover is an SVG placeholder
rather than a real generated image.