# Artisto > Design real screens with agents This application exposes the same capabilities over REST and MCP. Agents should prefer MCP. ## Authentication - REST: send an API key as `Authorization: Bearer ` (keys are created by the user in the app; prefix `zts_`). - MCP: the same bearer API key, or OAuth 2.1 with PKCE, discovered from https://artisto.so/.well-known/oauth-protected-resource. Read-only tools need the read scope; everything else needs the write scope. ## Endpoints - MCP server (Streamable HTTP): https://artisto.so/api/mcp - OpenAPI document: https://artisto.so/api/openapi.json - REST: POST https://artisto.so/api/v1/ with the arguments as a JSON object; GET https://artisto.so/api/v1 lists every method - OAuth authorization server metadata: https://artisto.so/.well-known/oauth-authorization-server ## MCP tools (read-only) - chats_byId (read-only): Get one of the caller's chats with its messages, oldest first, or null. - chats_folderById (read-only): Get one of the caller's chat folders by id, or null. - chats_folders (read-only): List the caller's chat folders in their sort order. - chats_mine (read-only): List the caller's chats without messages: pinned first, then most recently updated. - designs_app (read-only): Get one of the caller's design apps by id, or null. - designs_apps (read-only): List the caller's design apps, newest first. - designs_board (read-only): Get one of the caller's boards by id, including its theme CSS and DESIGN.md, or null. - designs_boards (read-only): List the boards of one of the caller's design apps, oldest first. - designs_comment (read-only): Get one of the caller's review comments by id, or null. - designs_comments (read-only): List the review comments on one of the caller's boards, oldest first. - designs_flow (read-only): Get one of the caller's flows by id, or null. - designs_flows (read-only): List the flows (ordered screen journeys) of one of the caller's boards. - designs_screen (read-only): Get one of the caller's screens by id, or null. - designs_screens (read-only): List the screens on one of the caller's boards, with position, devices and spec. - designs_variant (read-only): Get one of the caller's screen variants by id, with its TSX source, or null. - designs_variants (read-only): List every variant (TSX source included) of the screens on one of the caller's boards. - todos_archived (read-only): List the caller's archived todos, newest first. - todos_byId (read-only): Get one of the caller's todos by id, or null. - todos_mine (read-only): List the caller's active and paused todos, newest first. - users_me (read-only): Get the caller's own profile: name, email, username, bio, timezone, role, onboarding state, raw preferences, and the avatar and cover images (UploadThing keys). Null when the user no longer exists. ## MCP tools (write) - admin_envVars: Admins only: list the deployment environment variables (Coolify, Vercel, Railway, Render, PORT, HOST, SOURCE_COMMIT), null when unset. - aiProviders_clearKey: Delete the caller's stored API key for an AI provider. - aiProviders_list: List every AI provider with whether the caller enabled it and stored a key (only the key's last 4 characters). - aiProviders_setEnabled: Turn an AI provider on or off for the caller's chats. - aiProviders_setKey: Store the caller's API key for an AI provider, encrypted, replacing any previous key. Returns its last 4 characters. - apiKeys_create: Create an API key for the caller (expiresIn in seconds, null never expires). Returns the record with the full `key`, which is shown only this once. - apiKeys_delete: Delete one of the caller's API keys; requests using it fail from then on. - apiKeys_get: Get one of the caller's API keys by id, without the secret. - apiKeys_list: List the caller's API keys, newest first, without the secrets. - apiKeys_update: Rename, enable or disable, re-expire or re-tag one of the caller's API keys, and return it. - auth_changePassword: Change the caller's password (8-128 characters, confirmed) after checking the current one, and sign out every other session. - billing_state: Get the caller's billing state from Polar: active subscriptions, granted benefits, and isPro (holds the Pro benefit). When billing is off it answers id "noop" with nothing active. - chats_create: Start a chat and return it. Defaults: title 'New chat', intelligence 'standard'. - chats_createFolder: Create a chat folder at the end of the caller's folder list and return it. - chats_deleteFolder: Delete a chat folder. Its chats are kept and move out of the folder. - chats_moveToFolder: Move a chat into one of the caller's folders, or out of any folder with null, and return it. - chats_remove: Delete a chat and all of its messages permanently. - chats_rename: Rename a chat and return it. - chats_renameFolder: Rename a chat folder and return it. - chats_setPinned: Pin a chat to the top of the list, or unpin it, and return it. - chats_updateSettings: Change a chat's AI provider, model or intelligence level (only the fields given), and return it. - designs_addComment: Pin a review comment to one or more points, areas or elements of a variant (coordinates are fractions of the frame) and return it. - designs_createApp: Create a design app (a product with boards) and return it. The id is generated when omitted. - designs_createBoard: Create an empty board in one of the caller's design apps and return it. Boards sharing a variantGroup are whole-board variants of each other. - designs_createScreen: Add a screen to one of the caller's boards with its first variant (TSX with a default export; starter code when omitted), and return the screen. - designs_createVariant: Add a design variant (TSX with a default export) to one of the caller's screens and return it. - designs_removeApp: Delete a design app with all its boards, screens, variants, flows and comments. - designs_removeBoard: Delete a board with all its screens, variants, flows and comments. - designs_removeComment: Delete a review comment. - designs_removeFlow: Delete a flow. Its screens stay on the board. - designs_removeScreen: Delete a screen with its variants and their comments. - designs_removeVariant: Delete a variant. A screen showing it falls back to its oldest remaining variant. - designs_resolveComment: Mark a review comment resolved or open again, and return it. - designs_saveFlow: Create or replace a flow (an ordered list of screen ids on one of the caller's boards) and return it. - designs_updateApp: Rename a design app or change its description, and return it. - designs_updateBoard: Change a board's name, devices, appearance, variant group, theme CSS (shadcn tokens), DESIGN.md or Google fonts, and return it. - designs_updateScreen: Change a screen's name, slug, canvas position, devices (null = all of the board's), spec (Markdown) or selected variant, and return it. - designs_updateVariant: Change a variant's name, TSX code or liked flag, and return it. - todos_create: Create a todo and return it. The id is generated when omitted. - todos_export: Export the caller's active and paused todos as a Markdown checklist. - todos_plan: Set the day a todo is planned for (YYYY-MM-DD), or null to unplan it, and return it. - todos_remove: Delete a todo permanently. - todos_setDone: Mark a todo done or not done, and return it. - todos_setStatus: Pause, archive or reactivate a todo, and return it. Archived todos drop out of todos.mine. - uploads_delete: Delete one of the caller's uploaded images from storage and the database; a profile using it as avatar or cover loses that image. - users_markOnboarded: Mark the caller as onboarded and return the profile. - users_resendVerificationEmail: Send the caller a new email verification link (at most one a minute, five an hour), and return the updated limits. - users_resetOnboarding: Reset the caller's onboarding so the onboarding flow shows again, and return the profile. - users_setPreference: Set one boolean preference (notifications, sound, analytics, emailMarketing, emailUpdates, aiProviderEnabled) and return the profile with its preferences. - users_updateProfile: Update the caller's name, username, bio, timezone and avatar/cover image (an uploaded image id, or null to remove it), and return the profile. Omitted fields keep their value; an empty username clears it. - users_verificationEmailStatus: Get whether the caller can request another verification email and when (ISO time); null when verification is off or the email is already verified. ## Notes - MCP tool names are the REST method names with `.` replaced by `_` (`todos.create` is the tool `todos_create`). - Tool input schemas are served by the MCP `tools/list` method and match the OpenAPI request bodies.