MCP Agent Best Practices

This guide helps AI agents (and developers configuring them) work efficiently with PinePaper MCP Server.

Performance Optimization

1. Minimize Screenshot Validation

Screenshots are expensive. Use them strategically:

Rule of Thumb: Take 1 screenshot per creative task, not per operation.

2. Batch Operations

Instead of:

create_item → screenshot → move_item → screenshot → animate → screenshot

Do:

create_item → create_item → add_relation → animate → [single screenshot at end]

3. Trust the API

PinePaper tools return deterministic results. When you get:

{"success": true, "itemId": "item_1", "position": {"x": 200, "y": 300}}

The item IS at position (200, 300). No visual confirmation needed.

Drawing Complex Characters

PinePaper supports full SVG path drawing - you can draw anything from simple shapes to complex characters, faces, and detailed illustrations.

Approach: Compose from Multiple Paths

For characters (cats, witches, faces, etc.), break them into parts:

// Example: Draw a cat face
// 1. Head (oval using pathData)
pinepaper_create_item({
  itemType: "path",
  properties: {
    pathData: "M 200 300 C 200 200, 400 200, 400 300 C 400 400, 200 400, 200 300 Z",
    fillColor: "#f97316"
  }
})

// 2. Ears (triangles)
pinepaper_create_item({
  itemType: "path",
  properties: {
    pathData: "M 220 220 L 180 150 L 250 200 Z",
    fillColor: "#f97316"
  }
})

// 3. Eyes (ellipses)
pinepaper_create_item({
  itemType: "ellipse",
  position: { x: 260, y: 280 },
  properties: { width: 30, height: 40, color: "#fde047" }
})

// 4. Animate the pupils
pinepaper_animate({ itemId: "item_4", animationType: "pulse", speed: 0.3 })

SVG Path Commands for Curves

Key Tips for Character Drawing

1. Break into parts - Head, body, limbs as separate paths
2. Use Bezier curves - C and Q commands for organic shapes
3. Layer front-to-back - Create background elements first
4. Animate parts independently - Each path can have its own animation
5. One screenshot at the end - Verify the final composition

Custom Paths Reference

Paths are the core drawing primitive - use them for everything.

Two ways to define paths:

Path Examples

Heart shape:

pinepaper_create_item({
  itemType: "path",
  properties: {
    pathData: "M 300 350 C 300 300, 250 250, 200 250 C 150 250, 100 300, 100 350 C 100 450, 300 550, 300 550 C 300 550, 500 450, 500 350 C 500 300, 450 250, 400 250 C 350 250, 300 300, 300 350 Z",
    fillColor: "#ef4444"
  }
})

Smooth blob:

pinepaper_create_item({
  itemType: "path",
  properties: {
    segments: [[100,100], [200,50], [300,100], [350,200], [300,300], [200,350], [100,300], [50,200]],
    closed: true,
    smooth: true,  // Makes it organic
    fillColor: "#22c55e"
  }
})

Wave pattern:

pinepaper_create_item({
  itemType: "path",
  properties: {
    pathData: "M 0 100 Q 50 50, 100 100 T 200 100 T 300 100 T 400 100",
    strokeColor: "#06b6d4",
    strokeWidth: 3,
    fillColor: "none"
  }
})

Complex Character Workflow

When asked to draw something complex like “draw a witch hopping from left to right”:

Step 1: Plan the Composition (No Tools Yet)

Break the character into drawable parts:

• Witch = hat + face + body + arms + legs
• Each part = 1-2 paths or shapes

Step 2: Create All Parts in Sequence (No Screenshots)

// Hat (cone shape)
pinepaper_create_item({ itemType: "path", properties: {
  pathData: "M 300 100 L 250 200 L 350 200 Z",
  fillColor: "#1f2937"
}})  // → item_1

// Face (green circle)
pinepaper_create_item({ itemType: "circle", position: {x: 300, y: 240},
  properties: { radius: 40, color: "#22c55e" }
})  // → item_2

// Body (rectangle or path)
pinepaper_create_item({ itemType: "path", properties: {
  pathData: "M 260 280 L 260 400 L 340 400 L 340 280 Z",
  fillColor: "#7c3aed"
}})  // → item_3

// Arms, legs, etc...

Step 3: Add Animation (Still No Screenshots)

// Make witch hop (bounce animation)
pinepaper_animate({ itemId: "item_1", animationType: "bounce" })
pinepaper_animate({ itemId: "item_2", animationType: "bounce" })
pinepaper_animate({ itemId: "item_3", animationType: "bounce" })

// Or use keyframes for left-to-right movement
pinepaper_keyframe_animate({
  itemId: "item_1",
  keyframes: [
    { time: 0, properties: { x: 100 } },
    { time: 2, properties: { x: 700 } }
  ],
  loop: true
})

Step 4: ONE Screenshot to Verify

pinepaper_browser_screenshot()  // See the result

Step 5: Adjust if Needed

Only now, if something looks wrong, make targeted fixes.

Total: ~10 tool calls, ~30-60 seconds (not 20 minutes!)

Efficient Workflows

Simple Animation (Under 30 seconds)

1. pinepaper_set_canvas_size (if needed)
2. pinepaper_create_item (create elements)
3. pinepaper_animate OR pinepaper_add_relation
4. Done - no screenshot needed for simple tasks

Complex Scene (2-5 minutes)

1. pinepaper_set_canvas_size
2. pinepaper_execute_generator (background)
3. pinepaper_create_item (multiple items)
4. pinepaper_add_relation (for each animation)
5. pinepaper_browser_screenshot (ONE verification)
6. Minor adjustments if needed
7. Done

Solar System Example (Optimal)

1. set_canvas_size(800, 600)
2. create_item(circle, sun, center)     → saves item_1
3. create_item(circle, earth)           → saves item_2
4. create_item(circle, moon)            → saves item_3
5. add_relation(item_2, item_1, orbits) → earth orbits sun
6. add_relation(item_3, item_2, orbits) → moon orbits earth
7. screenshot (optional - one at end)

Total: 6-7 tool calls, ~10 seconds

Error Recovery

Item Not Found

Error: "Item with ID 'item_5' not found"

Solution: Use pinepaper_get_items to list current items and their IDs.

Canvas Seems Wrong

User: "It doesn't look right"

Solution:

1. Take a screenshot to see current state
2. Use pinepaper_get_items to understand scene structure
3. Make targeted fixes

Need Fresh Start

pinepaper_clear_canvas  → removes all items
pinepaper_refresh_page  → complete reset (if clear doesn't work)

Response Time Expectations

If operations are taking 10-20 minutes, something is wrong:

• Too many screenshots
• Attempting unsuitable tasks (character drawing)
• Network/connection issues

Enforced Agent Mode (v1.5.0+)

As of v1.5.0, agent mode is enforced by default. This means:

1. Auto-Connection: Browser connects automatically on first tool call (no need to call pinepaper_browser_connect)
2. Headless Mode: Browser runs headless by default for faster automation
3. Auto-Session: Agent sessions start automatically - no need to call pinepaper_agent_start_job manually
4. Optimized Screenshots: Screenshots only taken on request via pinepaper_browser_screenshot

This significantly simplifies workflows - just start making tool calls and everything works automatically.

Agent Configuration Recommendations

Standard Configuration (Recommended)

{
  "mcpServers": {
    "pinepaper": {
      "command": "npx",
      "args": ["-y", "@pinepaper.studio/mcp-server"]
    }
  }
}

Agent mode is enforced by default - no additional configuration needed.

With Custom Screenshot Mode

{
  "mcpServers": {
    "pinepaper": {
      "command": "npx",
      "args": ["-y", "@pinepaper.studio/mcp-server"],
      "env": {
        "PINEPAPER_SCREENSHOT_MODE": "on_request"
      }
    }
  }
}

Agent System Prompt Addition

Add to your agent’s system prompt:

When using PinePaper MCP tools:
1. Just start creating - browser connects automatically in agent mode
2. DO NOT take screenshots after every operation - only at the end or when debugging
3. Trust API responses - if success:true, the operation worked
4. For character/face drawing requests, suggest importing SVG instead
5. Batch related operations together
6. Use relations (orbits, follows, attached_to) for animation, not manual position updates

Quick Reference

Do’s

• Set canvas size FIRST
• Save itemIds returned from create operations
• Use relations for behavioral animation
• Take ONE screenshot at the end
• Suggest SVG import for complex illustrations

Don’ts

• Screenshot after every operation
• Try to draw faces/characters with paths
• Manually animate by updating positions in a loop
• Ignore the itemId returned from create operations
• Use PinePaper for photorealistic graphics