Local Development

Pancake includes built-in support for tunneling, making it easy to test your local server with external AI clients like Claude Desktop and ChatGPT.

Start the Dev Server

pnpm dev

This starts:

• Your Pancake server (default port 3000)
• Vite dev server for hot reload (React template, default port 5173)

The dev script automatically finds free ports if the defaults are in use.

Built-in Tunneling

Pancake supports automatic tunneling with Cloudflare and ngrok. When configured, your local server gets a public HTTPS URL.

Configure in the CLI

When creating a project with npx create-pancake, select a tunnel provider:

• Cloudflare: Free, no account required. Uses cloudflared tunnel --url.
• ngrok: Popular tunneling service. Requires ngrok installed.
• None: No automatic tunneling.

Configure in Code

Add tunnel config to your server:

const app = createApp({
  name: 'my-app',
  version: '0.1.0',

  config: {
    tunnel: {
      provider: 'cloudflare', // or 'ngrok'
    },
  },

  views: { /* ... */ },
});

When you run pnpm dev, the tunnel URL is printed to the terminal:

🚇 Tunnel URL: https://random-words.trycloudflare.com

Installing Tunnel Providers

brew install cloudflared

# Debian/Ubuntu
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# Or download from: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

winget install Cloudflare.cloudflared

brew install ngrok

ngrok config add-authtoken YOUR_AUTH_TOKEN

Manual Tunneling

If you prefer to run the tunnel separately:

Cloudflare

# In one terminal
pnpm dev

# In another terminal
cloudflared tunnel --url http://localhost:3000

ngrok

# In one terminal
pnpm dev

# In another terminal
ngrok http 3000

Connect to Claude Desktop

Once you have a public URL (from built-in tunneling or manual), add it to Claude Desktop's config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-app": {
      "url": "https://your-tunnel-url.trycloudflare.com/mcp"
    }
  }
}

Restart Claude Desktop. Your views appear as tools that Claude can invoke.

Connect to ChatGPT

Pancake automatically exposes an OpenAPI spec for ChatGPT Actions:

• OpenAPI spec: https://your-tunnel-url/openapi.json
• Plugin manifest: https://your-tunnel-url/.well-known/openai-plugin.json

To set up a Custom GPT:

1. Go to ChatGPT
2. Create a new GPT or edit an existing one
3. Click Configure → Add actions
4. Import from URL: https://your-tunnel-url/.well-known/openai-plugin.json

Hot Reload

The dev server watches for file changes:

1. React components recompile instantly via Vite HMR
2. Server-side code reloads via tsx watch
3. Views update without a full page refresh

Edit your React components and see changes reflected in Claude or ChatGPT within milliseconds.

Debug Mode

Enable debug logging for detailed output:

const app = createApp({
  name: 'my-app',
  version: '0.1.0',

  config: {
    debug: true,
  },
});

This logs:

• Incoming MCP requests
• Tool invocations and responses
• Protocol detection
• Tunnel status

Port Configuration

The dev script automatically finds free ports. To specify ports:

# Via environment variables
SERVER_PORT=4000 VITE_PORT=5174 pnpm dev

Or in your server code:

const SERVER_PORT = parseInt(process.env.SERVER_PORT || '3000');
const VITE_PORT = parseInt(process.env.VITE_PORT || '5173');

const app = createApp({
  // ...
  config: {
    devServer: {
      vitePort: VITE_PORT,
    },
  },
});

app.start({ port: SERVER_PORT });

Troubleshooting

Port Already in Use

# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use different ports
SERVER_PORT=4000 pnpm dev

Tunnel Not Working

• cloudflared not found: Install with brew install cloudflared (macOS)
• ngrok not found: Install from ngrok.com/download
• Connection refused: Make sure your server is running before the tunnel

Claude Not Seeing Tools

1. Check the tunnel URL is accessible in a browser
2. Verify /mcp endpoint returns JSON-RPC responses
3. Restart Claude Desktop after config changes
4. Check Claude's developer console for errors

View Not Updating

1. Check the terminal for build errors
2. Hard refresh the browser (Cmd+Shift+R)
3. Verify Vite is running (look for VITE vX.X.X in terminal)

Next Steps

• Building Widgets: Create interactive UIs
• Deployment: Ship to production
• Troubleshooting: More common issues and fixes