MCP tools

Every tool the Posy MCP server offers, with its inputs.

The server is Streamable HTTP at https://posy.page/api/mcp (or https://YOUR-POSY/api/mcp on your own server). Sign in with OAuth, or send an API key as Authorization: Bearer posy_.... See Connect an AI app.

All edits go to your draft. Only publish makes anything public. Start every session with get_page.

Descriptions below come from the server (src/app/api/mcp/route.ts). npm run docs:sync fails if a tool is added there without being listed here.

Read

get_page · tool

The current draft (profile, theme, tiles with ids), public URL, version, whether there are unpublished changes, and a next hint. Read-only. Inputs: none.

list_options · tool

Allowed values for looks (with a note and the palettes each offers), themes, fonts, backgrounds, tile styles, sizes, colours and social platforms. Read-only. Inputs: none.

Create

create_page · tool

Claim a username and create the page (one per account). Do this once, when get_page says there is no page.

Input	Type	Notes
username	string, required	3 to 30 letters, numbers, - or _. Becomes the public URL.
style	enum	The look: cozy (Desk), washi, lofi, painted, cobalt, night. Omit for a starter template.
layout	enum	bento, list or canvas.
preset	enum	Colour theme (palette).
template	enum	A starter template.
empty	boolean	Start blank instead of with sample tiles. Recommended when you will add the user’s own links.

import_page · tool

Load a whole page at once from a page file (a brief or the full page JSON). Creates the page if there is none (pass username). With an existing page it replaces the draft only when replace is true. Marked destructive.

Input	Type	Notes
file	object or string, required	The brief or page JSON, as an object or text.
username	string	Needed when there is no page yet.
replace	boolean	Overwrite an existing draft. Ask the user first.

Tiles

add_tile · tool

Add tiles. Pass inputs for several, input for one, or a full tile object. Posy auto-detects links, emails, owner/repo and notes.

Input	Type	Notes
input	string	For example https://github.com/user, owner/repo, [e-mail], Open to work.
inputs	string[] (max 30)	Several inputs, added in order. Prefer this for a list of links.
tile	object	A full tile, for example {"type":"heading","text":"Projects"}.
after	string	Insert after this tile id. Default: the end.
size	enum	s, w, t or l.
color	enum	auto, surface, accent, peach, butter, mint, sky, lilac or rose.

update_tile · tool

Change fields of a tile, for example {"size":"l"}, {"title":"New title"}, {"color":"mint"}, {"text":"..."}. Crop a tile’s picture with {"focus":{"x":30,"y":20},"zoom":1.6} (focus 0 to 100 is the point to keep in view, zoom 1 to 3).

Input	Type	Notes
id	string, required	The tile id from get_page.
patch	object, required	The fields to change.

move_tile · tool

Move a tile to a 0-based position in the tile list.

Input	Type	Notes
id	string, required	The tile id.
position	integer, required	0 or more.

remove_tile · tool

Delete a tile by id. Marked destructive. Input: id (string, required).

Look and profile

set_theme · tool

Change colours, fonts, layout and other theme settings. Only pass what should change.

Input	Type	Notes
style	enum	The look: cozy, washi, lofi, painted, cobalt, night.
preset	enum	A palette. list_options shows which palettes each look offers.
accent	string	A hex colour such as #a5683f.
font, radius, align	enum	Typeface, corner radius, alignment.
layout	enum	bento, list or canvas.
tileStyle, effect, avatar	enum	Tile style, hover effect, avatar shape.
photos	enum	natural, mono, dither or ascii.
motion, ambient	boolean	Animation and ambience on or off.
background	object	style, image, dim, blur, grain, and color (hex).

set_profile · tool

Change name, bio, avatar URL or location.

Input	Type	Notes
name, bio, avatar, location	string	All optional.
avatarFocus	{x, y}	0 to 100 each. The point to keep in view.
avatarZoom	number	1 to 3.

Go live

publish · tool

Make the draft live at the public URL. Inputs: none.

Typical session

1. Look

   get_page. If there is no page, ask for a username.
2. Create

   create_page with empty: true, or import_page with a whole brief.
3. Fill

   add_tile with inputs[], then set_theme and set_profile.
4. Publish

   publish when the user is happy, then share the URL.