# Nanopage MCP Interface

Canonical HTML: https://nanopage.site/mcp (sign-in required to mint tokens)

Connect an AI coding agent (Claude Code, Claude Desktop, Cursor, Codex) to Nanopage over the Model Context Protocol. Your agent generates the site with its own model; Nanopage validates, stores, and hosts it at `{slug}.nanopage.site`.

## Endpoint

- **URL**: `https://api.nanopage.site/mcp` (also reachable at `https://nanopage.site/mcp` for POST)
- **Transport**: Streamable HTTP (JSON-RPC 2.0 over POST)
- **Auth**: standard MCP OAuth — add the endpoint URL and your client registers itself, opens your browser to sign in to Nanopage, and asks you to approve. Nothing to paste. For CI, headless machines, and clients that cannot open a browser, mint a personal access token at [nanopage.site/mcp](https://nanopage.site/mcp) and send it as `Authorization: Bearer np_YOUR_TOKEN`.
- **Scopes**: tokens carry the single scope `mcp` (publishing + read-back only, never dashboard/billing/admin), declared machine-readably per RFC 9728 at [api.nanopage.site/.well-known/oauth-protected-resource/mcp](https://api.nanopage.site/.well-known/oauth-protected-resource/mcp)
- **REST twin**: the same seven operations are available as a plain HTTPS + JSON API at `https://api.nanopage.site/v1`, described by [nanopage.site/openapi.json](https://nanopage.site/openapi.json)

Claude Code, via OAuth (no token):

```
claude mcp add --transport http nanopage https://api.nanopage.site/mcp
```

Static-token config for CI (`.mcp.json`):

```json
{
  "mcpServers": {
    "nanopage": {
      "type": "http",
      "url": "https://api.nanopage.site/mcp",
      "headers": { "Authorization": "Bearer np_YOUR_TOKEN" }
    }
  }
}
```

## Tools

- `publish_website` (write) — create a new site from a file bundle (index.html + assets + images)
- `publish_version` (write) — add a version to an existing site; auto-promotes unless `promote:false`
- `create_upload` (write) — upload URLs for images and other binaries, so the bytes never ride inside a tool call
- `list_websites`, `get_website`, `list_versions` (read)
- `get_job_status` (read) — publish jobs land ready immediately
- `suggest_slug` (read) — slug validity, availability, and fallback suggestion

## Sending images

A photo cannot be inlined as base64 in a tool call, so a publish file takes one of three bodies:

- `content` (+ `contentEncoding`) — text: HTML, CSS, JS, SVG.
- `sourceUrl` — a public https URL nanopage fetches the bytes from.
- `uploadKey` — from `create_upload`: `PUT` the file to the returned `putUrl` (the URL is the credential, no auth header), then publish `{ "path": "images/hero.webp", "uploadKey": "…" }`. Slots expire after an hour.

Limits: 50 MB per uploaded or fetched file, 1 GB per site, no file-count limit, and 200 `sourceUrl` fetches per hour per account. `sourceUrl` targets must be public https — private and link-local addresses are refused.

## Resources & prompts

- Resource `nanopage://spec/authoring-guide.md` — the authoring spec (file layout, hard rules, size limits). Read it before generating.
- Prompt `nanopage_publish_site` — bootstraps a publishable site from a topic with the spec inlined.

## Authoring rules (enforced at publish time)

Static sites only. Rejected: external scripts/styles/fonts (bundle inline), iframes/objects/embeds, `javascript:` URLs, service workers, off-site meta-refresh, forms posting to external hosts, anything needing a backend. Allowed layout: `index.html` plus up to 14 more `{slug}.html`, `assets/site.css`, `assets/{slug}.js`, `images/`, `files/`, `videos/`. Limits: 50 MB per file, 1 GB per site, no file-count limit.

Dynamic content works through MCP too: ship `collections.json` plus `templates/{collection}/list.html` (optionally `item.html` and `templates/pages/{page}.html`) and Nanopage creates the collections, seeds them, and renders the pages — blog, news, products, events, testimonials, FAQ, galleries, and visitor contact forms the owner then manages in the editor without a republish. The authoring spec resource documents the manifest and template language; `get_website` lists a site's existing collections and field schemas.

## Related

- [MCP server feature page](https://nanopage.site/mcp-server/)
- [Developer resources](https://nanopage.site/developers/)
- [Blog: Nanopage Now Has an MCP Server](https://nanopage.site/blog/nanopage-mcp-server-ai-coding-agents/)