# Pikes MCP Server

Connect an MCP-compatible assistant to the Pikes creative suite: saved brand
context, product and asset libraries, boards, editable projects, creative
production, and campaign insights. Work starts with the brand’s own materials
and stays organized in its Pikes workspace.

Pikes includes AI image generation and editing, video generation, and audio
generation. Media generation spends the connected account’s credits; account
permissions still apply to saved content. Meta analysis requires a separate
Meta connection in Pikes.

```
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 authenticated `tools/list` response supplies the current tool catalogue
and input schemas; the [API reference](/docs/api) covers HTTP usage and errors.

| Method | Transport |
| --- | --- |
| `POST /mcp` | JSON-RPC messages |
| `GET /mcp` | Server information (HTML requests redirect to settings) |
| `GET /mcp/sse` | Legacy SSE connection |
| `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.
Select Pikes in the chat before running a creative workflow. For editable
layouts, request an editable Pikes project, a preview and its project link.
The preview card opens the saved project; board links preserve their existing
visibility and require access to private boards.

## 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. CIMD clients may publish a set of supported token
authentication methods; Pikes accepts the intersection with its advertised
`none` and `client_secret_post` methods. A legacy singular preference does not
override the plural capability set. Unsupported assertions are rejected, not
ignored. Dynamic clients still use their registered authentication method.

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` |
| Projects & pages | `list_projects`, `create_project`, `update_project`, `list_project_pages`, `create_project_page`, `update_project_page` |
| Project canvas | `read_item_link`, `get_project_canvas`, `compose_project_frame`, `preview_project_frame`, `add_project_object`, `update_project_object`, `add_project_text`, `update_project_text`, `layout_project_canvas`, `remove_project_object`, `add_assets_to_project` |
| 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` |

For a pasted asset/frame link, call `read_item_link` with `{ "url": "https://pikes.ai/app/projects/<project-id>?page=<page-id>&object=<object-id>" }`. It returns the exact object and its current project/page location, including after a page move. Existing project access is required. Studio asset links (`https://pikes.ai/s/<asset-id>`) return the asset and project placements accessible to the connected user. A removed item returns an error.

The authenticated `tools/list` response is the source of truth for current
parameters and defaults. The [API reference](/docs/api#tool-catalogue) provides
HTTP examples. 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. Tools that call generation providers,
serve newly generated media through public URLs, or can change a public board
or an already-public project advertise `openWorldHint: true`. The hint covers
all supported modes, even when the particular request creates a private board.
It does not grant sharing permission or change an object's visibility. Private
project creation remains closed-world; renaming remains reversible.

### Projects and canvas editing

Native sections use `add_project_object` with `objectType:"note"`, a title in
`content`, `dataJson:'{"canvasSection":true}'`, and bounds enclosing the member
objects with padding. Membership is spatial and objects stay editable. To move
a section with its contents, include the section, enclosed objects, and nested
sections in `layout_project_canvas` with the same position delta.

Claude and other MCP clients use the same project operations as the Pikes agent
and web canvas. Existing OAuth/API-key authentication applies; project access
is limited to the caller's own projects and projects shared with their teams.

1. Call `list_projects`, then `list_project_pages` for the chosen project.
2. Read `get_project_canvas` with explicit `projectId` and `pageId`. It returns
   positions, dimensions, note text, editable frame layers, and asset URLs.
   Follow `nextOffset` until null when inspecting a whole page. This is structured
   canvas content, not a rendered screenshot.
3. Use `layout_project_canvas` for tidying; `add_project_object` for notes or
   frames; `add_project_text` to write on an image/frame; and
   `update_project_text` to edit one note or nested text layer. Text overlay
   creation preserves the underlying image and returns the new `layerId`.
   Note text edits also update the rich-text document used by the renderer,
   retaining paragraph/heading styles. Complex list documents become paragraphs
   on full-text replacement; use `dataJson` for precise document editing.
4. Canvas writes broadcast the saved objects to the private page channel so
   open browsers update without reload. A notification failure still reports
   the successful save with `canvasRefreshRequired`; refresh instead of repeating
   a write that already succeeded. Read the changed page back. Concurrent edits detected during text or frame
   updates return an error: reread before retrying. Layout batches can partially
   succeed if a database write fails; inspect before retrying.

All canvas writes require an explicit active page. Removing a canvas image
preserves its library asset and records the existing sync exclusions. Removing a
board also removes its linked canvas placements. Page trash is reversible.
Whole-project deletion and sharing changes are not exposed by these tools.

Optional arguments can be omitted in MCP. `dataJson`, when supplied, is a JSON
object encoded as a string and replaces the complete object data; preserve
existing fields and layers. Frame layers paint bottom to top in the frame's
native pixel coordinates. External MCP clients discover their project and page explicitly; they do not
inherit the open browser tab.

After a server release, clients that cache discovery may need to refresh the
connector or reconnect to receive the new tool list. No new database migration
or credentials are required for these tools.

### 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-v3` | MCP App: media, voices, boards, products, context, jobs, colors, and ad data (`results-v2` remains a compatibility alias) |
| `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.

### Discovery requests require 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`.

The JSON catalogue at `GET /mcp` (also `/mcp/info`) includes the same top-level
`resource`, `authorization_servers`, and other protected resource metadata.
Codex sign-in reads the configured MCP URL directly before following discovery;
a catalogue without these fields fails with “Protected resource metadata missing
required resource field” even when the `.well-known` endpoints are correct.

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

An authentication `401` from the `/mcp` JSON-RPC endpoint 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/)

## Four creative-suite workflows

These examples use the connected account’s own brand data and assets. Generation
requires sufficient credits. Meta analysis additionally requires an authorized
Meta connection; the other workflows do not.

### Build a campaign from saved brand assets

“Read our saved brand guidelines and palette, find our product packshots, and
create a private Summer Launch board with the relevant assets. Tell me what is
missing before creating new media.”

Expected result: a private board containing accessible existing assets, with
saved brand context informing the selection. No new generation is needed.

### Compose an editable campaign layout

“Create a private Summer Launch project with a concept page. Arrange our saved
product assets and a headline in an editable square layout. Preview the result
and check for text overflow.”

`compose_project_frame` creates native image, text, and graphic layers from a
layer plan and prepared assets. `preview_project_frame` renders the actual saved
frame and returns a preview URL, overflow measurements, and a visual critique.
The saved layers remain editable. A structural success alone does not establish
visual quality.

### Produce and organize campaign media

“Using the selected packshot and saved brand colors, make two lifestyle-image
variations. After I choose one, animate it into a short product video. Save the
outputs and add them to our Summer Launch board. Confirm the creative direction
and credit-using steps with me first.”

Expected result: saved image and video assets linked to the campaign board.
Generation spends Pikes credits. A pending job or failed render is not a completed
asset; completed results contain the saved asset IDs and media URLs.

### Use campaign performance to inform the next brief

“Compare our connected Meta ad creatives over the last 30 days by spend,
purchases, and ROAS. Identify supported patterns and propose three concepts using
our saved brand context. Do not publish ads, change budgets, or generate assets.”

Expected result: observations tied to the requested dates, account currency,
and retrieved metrics, plus a proposed brief. Pagination limits and unavailable
metrics should remain explicit. Competitor-ad longevity is not proof of returns.
The connector does not publish ads or change campaign budgets.

## Troubleshooting and review setup

- **Sign-in or 401 response:** reconnect and complete OAuth. A session ID is a
  routing identifier, not an access credential. Protected calls need a current
  bearer token or API key.
- **Permission denied:** confirm the account has access to the project, page,
  board, or asset. IDs do not confer access to another account’s data.
- **No saved products or assets:** import or upload appropriate source material;
  an empty library response does not mean new media has been created.
- **Insufficient credits:** check the account balance before requesting new
  generation. Reading assets and preparing a brief need no media generation.
- **Meta not connected:** connect an authorized Meta account in Pikes for ad
  analysis. Brand-library and design workflows remain separate.
- **Rendering failure or partial layout update:** inspect the reported job or
  saved page before retrying. A repeated generation request may incur another
  charge; a layout batch may already have applied some changes.

A reviewer workspace should contain a fictional brand brief, an exact color
palette, product images, an asset folder, a private board, and an editable project
with text and image layers. Full media testing also requires credits. Meta review
requires a separately authorized test account with real accessible metrics;
synthetic metrics must not be presented as live Meta results.

Support: [leo@pikes.ai](mailto:leo@pikes.ai). Data handling and retention:
[Privacy policy](https://pikes.ai/privacy).