MCP server reference

Everything an MCP client, or a developer wiring one up, needs: where the server is, how to sign in, the tools and their parameters, and what errors mean.

The server

Endpoint: https://pocketui.app/api/mcp, Model Context Protocol over Streamable HTTP.
Stateless: every request is a JSON-RPC message sent with POST; responses are JSON. There is no session to keep, and GET/DELETE return 405.
Headers: Content-Type: application/json, Accept: application/json, text/event-stream and Authorization: Bearer <token>.
Read-only: every tool reads the library and is marked readOnlyHint. Nothing can be created, changed or deleted.
Plans: every plan, Free included. Reads never count as exports.

Endpoints

Method	Path	What it does
`POST`	`/api/mcp`	MCP: `initialize`, `tools/list`, `tools/call`.
`GET`	`/.well-known/oauth-protected-resource/api/mcp`	Protected resource metadata (RFC 9728): which server issues tokens. Also served at `/.well-known/oauth-protected-resource`.
`GET`	`/.well-known/oauth-authorization-server`	Authorization server metadata (RFC 8414): every URL below.
`POST`	`/api/oauth/register`	Dynamic client registration (RFC 7591).
`GET`	`/api/oauth/authorize`	Starts sign-in: authorization code with PKCE. Opens the PocketUI consent screen.
`POST`	`/api/oauth/token`	Trades a code for tokens, and refreshes them.
`POST`	`/api/oauth/revoke`	Ends a grant (RFC 7009). Either token works.

Signing in with OAuth

OAuth 2.1 as the MCP authorization spec describes it, so MCP clients connect with the URL alone. A request without a token gets 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/api/mcp", which is where discovery starts.

Scope: library:read, the only one. Other requested scopes are ignored.
PKCE: required, S256 only.
Clients: register with token_endpoint_auth_method none (public, PKCE only), client_secret_post or client_secret_basic. Grants: authorization_code and refresh_token.
Redirect addresses: https, http on localhost/127.0.0.1 (any port), or an app scheme such as cursor://. Matched exactly; loopback ports may change.
Resource: if you send resource (RFC 8707), it must be the MCP endpoint or the site origin. Tokens only work on /api/mcp.
Tokens: access tokens last 1 hour; refresh tokens 90 days and rotate on every refresh (the old one stops working). Both are opaque.
Consent: every connection is approved by the user on the consent screen, and listed under AI → Connected apps in their profile until they disconnect it.
Responses include iss (RFC 9207) alongside code and state.

Personal tokens

For scripts and tools set up by hand: create one in your profile under AI → Personal token. It starts with pk_, is shown once, works until revoked, and is sent the same way: Authorization: Bearer pk_….

Call a tool with curl

curl https://pocketui.app/api/mcp \
  -H "Authorization: Bearer $POCKETUI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_folders","arguments":{}}}'

Tools and parameters

Types: SaveType is one of color, gradient, image, font, svg, clip, component, bookmark. Folder IDs are UUIDs; a folder reference is its name with @, like @Dark UI. Every tool returns its result as JSON text.

Tool	Parameters	Returns
`get_library_index`	`limitPerFolder` number 1–25, default 8 · `type` SaveType, optional	Folders with their `@` references and most recent saves
`get_folders`	None	Folders with `@` references and save counts
`get_folder_context`	`folderRef` string, required (ID or `@Name`) · `type` SaveType, optional · `limit` number 1–100, default 40 · `includePreview` boolean, default true	The folder, its saves ready for AI, and its combined design system
`get_item`	`ref` string, required (ID or `@Folder / Save name`) · `includeRelated` boolean, default true	One save in full, plus related saves from its folder
`get_saves`	`folderId` UUID, required · `type` SaveType, optional	The folder’s saves
`get_components`	`folderId` UUID, optional	Components with HTML, CSS, fonts and size
`get_color_palette`	`folderId` UUID, optional	Colors with hex, label and source
`get_typography`	`folderId` UUID, optional	Fonts with family, weights and sizes
`get_svgs`	`folderId` UUID, optional	SVG markup and viewBox
`get_design_system`	`folderId` UUID, optional	Colors, fonts and gradients as design tokens
`search_library`	`query` string, required · `type` SaveType, optional · `folderId` UUID, optional	Matching saves

Errors and limits

Response	Meaning
`401` on `/api/mcp`	No token, or it is invalid, expired or revoked. `WWW-Authenticate` says where to sign in (`error="invalid_token"` when a token was sent).
`405`	`GET` or `DELETE` on `/api/mcp`: the server is stateless, use `POST`.
`406`	The `Accept` header is missing `application/json` or `text/event-stream`.
`429`	Too many requests. Per minute and address: 120 on `/api/mcp`, 60 on `/api/oauth/*`, 10 registrations.
`invalid_client`	Unknown `client_id`, wrong secret, or a redirect address the client did not register.
`invalid_grant`	The code is used, expired or for another client; the PKCE verifier is wrong; or the refresh token was rotated or revoked.
`invalid_target`	The `resource` is not the PocketUI MCP server.
Tool result `{"error": "…"}`	The folder or save was not found, or does not belong to this user.

Tips

Testing a client? The MCP Inspector (npx @modelcontextprotocol/inspector) runs the whole sign-in against this server.