AI Integration
Pencil integrates with AI assistants through MCP (Model Context Protocol). All operations are local-first with a user-approval model -- every AI-proposed change requires your explicit confirmation before it touches your design file.
Supported AI Assistants
Pencil works with any assistant that speaks the MCP protocol. The following tools have been tested and verified:
Claude Code
Terminal-based AI coding agent with full MCP tool access.
Claude Desktop
Desktop app with native MCP support and visual context.
Cursor
AI-first code editor with inline design modifications.
Windsurf
Collaborative AI editor with real-time design integration.
Codex CLI
OpenAI command-line agent with MCP tool connectivity.
Antigravity
Lightweight AI assistant with MCP protocol support.
OpenCode CLI
Open-source terminal AI with extensible MCP tooling.
MCP Tools Available
The Pencil MCP server exposes three categories of tools that AI assistants can invoke on your behalf:
batch_designCreate, modify, or delete design elements in bulk.batch_getRead, search, and inspect elements across layers.get_screenshotRender visual previews of the current canvas or selection.snapshot_layoutAnalyze spatial structure, alignment, and hierarchy.get_editor_stateRetrieve the current editor context, selection, and mode.read_variablesRead design tokens and variable values.update_variablesUpdate design tokens and sync changes with CSS.Basic Usage
Open the AI prompt panel with the keyboard shortcut, describe what you want, and watch changes appear on canvas in real time.
# 1. Open the prompt panel
Cmd+K (macOS) / Ctrl+K (Windows / Linux)
# 2. Type your request
"Set the hero section background to a linear gradient from #1a1a2e to #16213e"
# 3. Approve the change
Review the diff, then press Enter to apply.
Example Requests
# Structural changes
"Add a 2-column grid with 24px gap to the features section"
"Duplicate the pricing card and update the title to Enterprise"
# Token updates
"Change --spacing-lg from 32px to 40px across all components"
# Analysis
"Take a screenshot and tell me if the nav items are vertically centered"
Best Practices
Getting good results from AI-assisted design comes down to clear, specific prompts. Follow these patterns for the best experience:
"Increase the primary button padding to 16px on all sides."
"Make it look better."
Specific values remove ambiguity and produce predictable results.
"Apply the spacing-lg token from our design system to the card gap."
"Add more space between the cards."
Referencing design system tokens keeps your file consistent.
"First set the layout grid to 12 columns, then align the hero section to span columns 2-11."
"Fix the layout."
Iterating from broad structure to fine detail reduces rework.
Iteration Strategy
Work from broad to detailed. Start with layout and structure, then refine spacing, typography, and color. This mirrors how design systems are built and minimizes the chance of an AI change cascading into unrelated areas.
Troubleshooting
If the AI assistant cannot connect to Pencil or changes are not reflecting, work through the following checklist:
Re-authenticate
Open the command palette and run Pencil: Re-authenticate MCP. This refreshes the session token.
Verify permissions
Ensure the AI assistant has been granted read and write scopes in Settings > AI > Permissions.
Restart services
Restart both the Pencil extension and the AI assistant. The MCP server process is managed by the extension and will respawn automatically.
Check the logs
Open the Output panel and select Pencil MCP from the dropdown. Connection errors and rejected tool calls are logged here.
Last updated: February 22, 2026