# Pikes MCP Server

Connect Claude, ChatGPT, Cursor — anything that speaks the Model Context
Protocol — to the Pikes image tools. The agent generates, edits, animates and
files images in the user's own Pikes account, spending that account's credits.

```
https://pikes.ai/mcp
```

Protocol `2025-06-18` (also accepts `2024-11-05`), Streamable HTTP with SSE for
streaming responses. The server identifies itself as `pikes-ai`, titled
**Pikes**, with PNG icons and a website URL so a client can show a proper
connector card rather than a bare string, and advertises three capabilities — **tools**, **prompts** and **resources**, each with
`listChanged`. The full tool catalogue, parameters and error codes live in the
[API reference](/docs/api).

| Method | Transport |
| --- | --- |
| `POST /mcp` | JSON-RPC messages |
| `GET /mcp` | SSE stream for server-initiated messages |
| `DELETE /mcp` | End a session (send the session id you were given) |

## Connect

### Claude (desktop or claude.ai)

1. [Install Pikes for Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Pikes&connectorUrl=https%3A%2F%2Fpikes.ai%2Fmcp).
2. Review the prefilled name (`Pikes`) and remote MCP URL (`https://pikes.ai/mcp`), then continue.
3. Authorize when prompted — the OAuth screen signs you into Pikes and hands the
   connector a scoped token. No API key to paste, nothing to rotate by hand.

### Claude Code / Cursor

```bash
claude mcp add --transport http pikes https://pikes.ai/mcp
```

Or in `.mcp.json`:

```json
{
  "mcpServers": {
    "pikes": {
      "type": "http",
      "url": "https://pikes.ai/mcp"
    }
  }
}
```

### ChatGPT

Add `https://pikes.ai/mcp` as a custom connector and authorize the same way.

## Authentication

**OAuth 2.1 (preferred).** Point the client at `https://pikes.ai/mcp` and it
discovers everything it needs:

```
GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource
```

PKCE (S256) is required. Clients that register themselves do so through
`POST /mcp/oauth/register` (RFC 7591); the rest of the flow runs through
`/mcp/oauth/authorize`, `/mcp/oauth/token` and `/mcp/oauth/revoke`. Scopes:
`generate_image`, `edit_image`, `expand_image`, `read_images`.

**API key.** For clients that can't complete OAuth, create a key under
**Settings → Claude / MCP** in the app and send it as either header:

```
Authorization: Bearer psk_…
x-api-key: psk_…
```

A key carries the full rights of the user who made it, so treat it like a
password: keys are stored only as a SHA-256 hash and can be revoked at any time
from the same screen.

## What the agent gets

| Group | Tools |
| --- | --- |
| Generate & edit | `generate_image`, `edit_image`, `expand_image`, `remove_background`, `upload_image` |
| Video | `animate_image` |
| Audio & voices | `generate_speech`, `generate_sound`, `generate_music`, `design_voice`, `list_voices` |
| Long renders | `submit_image_job`, `get_image_job` (returns a job id instantly; poll it) |
| Products & brand context | `get_product_images`, `fetch_products_from_website`, `get_all_context`, `update_context`, `get_account_info` |
| Boards | `list_boards`, `get_board_images`, `create_board`, `update_board`, `add_images_to_board`, `batch_rename_assets`, `list_teams` |
| Asset library & brand | `search_assets`, `list_asset_folders`, `create_asset_folder`, `file_assets_in_folder`, `get_brand_colors`, `save_brand_colors`, `save_product`, `set_naming_convention`, `manage_folders`, `manage_context_folders` |
| Presentation | `present_results` (all result types) |
| Research & Meta ads | `find_ads`, `meta_get_ads`, `meta_get_ad_insights`, `meta_get_ad_creative`, `meta_get_campaigns`, `meta_get_ad_comments`, `meta_get_page_comments`, `meta_get_audience_breakdowns`, `meta_get_ad_accounts` |

Every tool's parameters and defaults are documented in the
[API reference](/docs/api#tool-catalogue). Meta tools need the user's Meta
account connected in Pikes first.

Each tool ships a display title and the standard MCP annotations, so a client
knows what it is dealing with before it calls. Read tools carry `readOnlyHint`;
generation tools declare themselves as writes that are
not idempotent — the same prompt twice is two images and two charges — and
`update_context` and `batch_rename_assets` are marked `destructiveHint`,
because both replace what was there.

### Prompts

Four ready-made prompts, each taking arguments the client fills in:

| Prompt | Arguments |
| --- | --- |
| `product_photography` | `product_description` (required), `style`, `background` |
| `social_media_ad` | `product_or_service` (required), `platform`, `mood` |
| `brand_lifestyle` | `brand_values` (required), `target_audience`, `visual_style` |
| `product_on_model` | `product_image_url` (required), `context` (required), `style` |

### Resources

Once the connection is authorized, `resources/list` returns the account's own
material plus the shared interactive result view:

| Resource | What it is |
| --- | --- |
| `pikes://images/recent` | The account's recent generations |
| `pikes://images/<id>` | One generation, by id |
| `pikes://brand-profiles/active` | The active brand context (voice, colours, guidelines) |
| `pikes://brand-profiles/list` | A summary of that context |
| `ui://pikes/results-v2` | MCP App: media, voices, boards, products, context, jobs, colors, and ad data |
| `ui://pikes/image-viewer` | Compatibility alias for the shared result view |
| `ui://pikes/ad-preview` | Compatibility alias for the shared result view |

The `ui://` entries are MCP Apps (`text/html;profile=mcp-app`). Media creation
returns the view directly. Read and intermediate write tools return complete
`structuredContent` plus their existing text fallback, so agents can analyze and
chain results without repeatedly opening an iframe. Call `present_results` with
a source tool name and its result object to show the final selection. It supports
every advertised source tool and never executes that tool again.

The app uses the standard MCP Apps bridge and a self-contained HTML resource
(no external JavaScript dependency). It follows the host theme, reports its
content height, loads media on demand, and uses explicit host capabilities for
links, downloads, follow-up messages, and read-only job polling. A missing
capability leaves a usable fallback. No button generates or mutates saved data
automatically. A failed host action is shown inline, and cancellation stops job
polling. See [MCP app QA](mcp-app-qa.md) for the repeatable local check loop.

If a host caches the tool catalogue, refresh/reconnect Pikes once after upgrading
to discover `present_results`. Existing resource URIs remain supported.

### Everything answers 401 until you sign in

`initialize`, `tools/list` and `prompts/list` all return `401` without a
credential, carrying the challenge a client needs to build its sign-in link:

```
WWW-Authenticate: Bearer error="invalid_token",
  error_description="Authorization required",
  resource_metadata="https://pikes.ai/.well-known/oauth-protected-resource/mcp"
```

The JSON-RPC body carries the same thing in a form code can read — a stable
`data.code` of `auth_required` plus absolute `resource_metadata`,
`authorization_endpoint` and `registration_endpoint` URLs.

Protected Resource Metadata (RFC 9728) is served at every shape a client tries:
`/.well-known/oauth-protected-resource`, the path-inserted
`/.well-known/oauth-protected-resource/mcp`, and
`/mcp/.well-known/oauth-protected-resource`. Authorization server metadata
likewise answers at `/.well-known/oauth-authorization-server`, `…/mcp`, and
`/mcp/.well-known/oauth-authorization-server`.

## Calling a tool over plain HTTP

An orchestration layer that doesn't want an MCP client can call the same tools
directly — same auth, same arguments, JSON in and out:

```bash
curl -X POST https://pikes.ai/mcp/tools/generate_image \
  -H "x-api-key: psk_…" -H "Content-Type: application/json" \
  -d '{"prompt":"a matte black bottle on wet stone","aspectRatio":"4:5","resolution":"2K"}'
```

## When something fails

| Status | What it means |
| --- | --- |
| `401` | No credential, or a revoked/invalid key — the body names the header to use |
| `402` | Out of credits, or no active subscription; the body carries the shortfall |
| `429` | Rate limited (product-shot endpoints) |

A `401` always carries `WWW-Authenticate` and a `data.code` of `auth_required`;
follow `resource_metadata` to the authorization server rather than hard-coding
an endpoint.

Generations spend the connected account's credits, and a failed render is
refunded. `get_account_info` reports the balance without leaving the agent.

More: [API reference](/docs/api) · [Connecting an AI agent](/docs/ai) ·
[MCP specification](https://modelcontextprotocol.io/)