MCP connections

Lunar Paper offers a Model Context Protocol (MCP) endpoint for Pixel Art Studio. A connected AI chat can list projects, read pixels, create and edit artwork, and preview animation. It covers Pixel Art Studio only.

Enable access

1. An administrator enables Pixel Art MCP under Administration → Platform → MCPs. Turning it off blocks every connection at once.
2. Each user creates a token under Profile → Security → Personal MCP token. It is shown once, expires after 90 days, and can be rotated or revoked.
3. The user needs read access to a service to read its projects, and edit access to change them. Tools take the numeric serviceId, found in the service URL after /services/.

The built-in Pixel Art assistant uses the same tools without a token, even when external access is off. See built-in chat tools.

Connect a client

The endpoint is shown on the token panel, in the form https://paper.example.com/mcp/pixel-art. Add it to any client that supports Streamable HTTP MCP servers, with the token as a Bearer token. Keep the token in the client’s secret store or an environment variable, never in a prompt. A localhost endpoint only works for a client on the same computer.

For Codex, save the token in an environment variable named LUNAR_PAPER_MCP_TOKEN and run:

codex mcp add lunarPaperPixelArt --url https://paper.example.com/mcp/pixel-art --bearer-token-env-var LUNAR_PAPER_MCP_TOKEN

Or add it to config.toml:

[mcp_servers.lunarPaperPixelArt]
url = "https://paper.example.com/mcp/pixel-art"
bearer_token_env_var = "LUNAR_PAPER_MCP_TOKEN"

Restart Codex and start a new chat. Check it with codex mcp get lunarPaperPixelArt.

Example prompts

Replace 42 with your service ID:

Use the lunarPaperPixelArt MCP for service 42. List my Pixel Art projects.

Create a 32×32 pixel art project in service 42. Draw a sunset landscape with clouds, animate the clouds across eight frames, and show an animation contact sheet.

Tools

• Read: list_projects, get_project, get_frame_pixels, get_rig.
• Change: create_project, apply_actions, import_png, restore_history.
• Preview and check: preview_frame, preview_animation_sheet, preview_animation, preview_rig, analyze_animation.
• Help: action_guide lists the supported drawing, posing and timeline actions; list_history lists undo checkpoints.

Every edit must be based on the project’s latest updatedAt. If the project changed, the edit is rejected with PROJECT_CONFLICT and the chat must read it again. Each edit returns an undoHistoryId for restore_history; a project keeps 50 history entries. For a full character workflow, see Animate through MCP.

Every successful tool call is recorded in the service and platform audit logs, without the token.

If the connection fails

Symptom	Check
Authentication required	Pixel Art MCP is enabled, the token is current, and the client has loaded it. Restart the client after changing its environment.
Service not found or access denied	The service ID is right and the user has access.
Project changed	Ask the chat to read the project again.
A tool is listed but cannot be called	Reconnect the client and start a new chat.
Connection refused or timeout	Lunar Paper is running and the client can reach the exact endpoint. A remote client cannot use localhost.