The Aveiro MCP server wraps /api/v1 with tools like aveiro_list_pages and aveiro_update_page. Install it in Cursor, set AVEIRO_API_TOKEN, and agents can read and write draft MDX — publishing still happens in the editor.
What it is
The Aveiro MCP server is a small Model Context Protocol bridge shipped in the Aveiro repository under mcp/aveiro/. It exposes the same draft-content API as API tokens, but as named tools Cursor agents can call directly.Draft-only: the MCP server never publishes. Review changes in the editor and publish manually.
When to use it
Use the MCP server when you want an AI agent in Cursor (or another MCP client) to:
List sites and draft pages
Create or update MDX drafts from your repo
Check which pages have unpublished edits
Use raw HTTP or CI scripts when you do not need MCP — for example GitHub Actions syncing docs from git.
Prerequisites
An API token with scopes sites:read, content:read, and content:write.
The token secret () stored as in your environment.
av_live_…
AVEIRO_API_TOKEN
Cursor (or another MCP host) with MCP enabled.
Setup in Cursor
1. Set environment variables
2. Add .cursor/mcp.json in the project where the agent runs
If you have the Aveiro repo checked out, copy mcp/aveiro/.cursor/mcp.json.example to your project root and point args at the absolute path of mcp/aveiro/src/index.ts.
3. Reload Cursor
Save the file, then Reload Window. In Settings → MCP, the aveiro server should show a green status.
List a site's uploaded images — reuse before uploading (content:read)
aveiro_prepare_media_upload
Signed-URL handshake to add an image to site media (content:write)
aveiro_me
Verify token, scopes, and allowed sites
aveiro_list_sites
List accessible sites
aveiro_list_templates
List marketplace templates available to clone (optional category filter)
aveiro_create_site
Create a site — pass a template slug to clone pages, layout, and style (sites:write)
aveiro_list_pages
List draft pages in a site
aveiro_get_page
Read one page by path or content ID
aveiro_create_page
Create a draft MDX page
aveiro_update_page
Update draft content or metadata
aveiro_delete_page
Soft-delete a draft page
aveiro_list_changes
List unpublished edits awaiting review
Pass site_id on each tool call, or set AVEIRO_SITE_ID once in the MCP env block.
Authoring guidance
Before the first aveiro_create_page or aveiro_update_page call, agents should call aveiro_authoring_guide. It returns the shared Aveiro MDX doctrine — linear editorial structure, registered components only, and strict contracts for LineChart, OgCard, Collection, and images.
Page writes that pass MDX validation but read off-dialect (button rows, hand-rolled heroes, bare link lists) still succeed; the API response includes an advisory recommendations array describing suggested rewrites. See Create a page for the format.
For images, call aveiro_list_media first and reuse library URLs. When a new image is needed, aveiro_prepare_media_upload returns a short-lived signed URL — PUT the raw bytes, then embed the returned publicUrl in MDX. See Site media API.
Bootstrap from a marketplace template
Agents spinning up a new client site should clone a marketplace template instead of starting blank:
Call aveiro_list_templates (or GET /api/v1/templates) to browse approved templates — each row includes slug, label, category, and a preview_url.
Call aveiro_create_site with name, slug, and template set to that slug. The new site copies the template's pages, layout, and styles from the live template host (updates to the gallery template apply to future clones).
Continue with aveiro_list_pages / aveiro_update_page on the returned site id.
Requires sites:write on the token. Cloning large templates can take several minutes — the MCP client uses an extended timeout for template creates.
Use npm run inspector to test tools interactively.
Connect from ChatGPT and Claude
The hosted MCP server works with any remote MCP client — not only Cursor. Paste one URL:
ChatGPT: Settings → Connectors → add a custom connector with that URL, then sign in and pick the organization to grant. Claude.ai / Claude Desktop: Settings → Connectors → same URL and OAuth flow.
OAuth-capable clients never see your API token secret. The grant is scoped to the organization you choose and revocable from the dashboard. For scripts and CI, use a personal access token with Authorization: Bearer instead.
Every Aveiro MCP tool declares behaviour hints alongside its description:
Hint
What it means
readOnlyHint
The tool only reads workspace data — no drafts, media, or settings change.
destructiveHint
The tool can delete or irreversibly remove something (for example aveiro_delete_page).
openWorldHint
Always false for Aveiro — tools act only on your Aveiro API, never the open web.
idempotentHint
Repeating the same call with the same inputs has the same effect (PATCH-style updates and soft-deletes).
MCP hosts such as ChatGPT use these hints to decide when to ask for confirmation before running a tool. The hosted server at https://www.aveiro.app/api/mcp/mcp and the stdio server in mcp/aveiro/ now expose the same annotations on every tool — reads, writes, publishes, social drafts, newsletter drafts, and video mockups included.
Publishing still requires the publish:write scope on the token or OAuth grant. No tool can approve or send social posts or newsletters autonomously.
