Protocol Detection

Pancake automatically detects whether your view is running in Claude (MCP), ChatGPT (OpenAI), or another environment. Your code works the same everywhere.

How It Works

When your view loads, Pancake checks for environment markers:

// Simplified detection logic
function detectProtocol() {
  // Check for ChatGPT environment
  if (typeof window !== 'undefined' && window.openai) {
    return 'openai';
  }

  // Default to MCP (postMessage-based)
  return 'mcp';
}

The SDK then loads the appropriate adapter for communication.

Protocol Comparison

MCP (Claude, etc.)

Uses postMessage with JSON-RPC 2.0:

View (iframe) ◄──postMessage──► Host App

Aspect	Details
Communication	Window postMessage
Protocol	JSON-RPC 2.0
Security	Origin validation, handshake

OpenAI (ChatGPT)

Uses the window.openai API:

View ◄──window.openai──► ChatGPT Runtime

Aspect	Details
Communication	Direct API calls
Protocol	Promise-based methods
Security	ChatGPT sandbox

Server-Side Protocol Detection

On the server, Pancake detects the protocol from request headers:

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

  config: {
    // Auto-detect (default), or force a specific protocol
    protocol: 'both', // 'mcp' | 'openai' | 'both'
  },
});

When set to 'both', Pancake:

Responds to /mcp with MCP JSON-RPC
Responds to /openapi.json with OpenAPI spec
Responds to /.well-known/openai-plugin.json with plugin manifest

Using the Provider

Wrap your view with PancakeProvider:

import { PancakeProvider } from '@pancake-apps/web';

function App() {
  return (
    <PancakeProvider>
      <MyView />
    </PancakeProvider>
  );
}

The provider handles protocol detection and adapter initialization automatically.

Checking the Active Protocol

Use the useHost hook to check which protocol is active:

import { useHost } from '@pancake-apps/web';

function MyView() {
  const host = useHost();

  // host includes protocol information
  console.log('Theme:', host.theme);
  console.log('Display mode:', host.displayMode);

  return <div>Running in AI host</div>;
}

Debug Mode

Enable debug logging to see protocol detection:

// In your server config
config: {
  debug: true,
}

This logs:

Detected protocol
Incoming requests
Response formatting

Why This Matters

Without protocol abstraction, you'd write platform-specific code:

// Without Pancake
if (typeof window.openai !== 'undefined') {
  const data = window.openai.toolOutput;
  window.openai.callTool('search', { query });
} else {
  const data = await waitForMcpNotification();
  postMessage({ jsonrpc: '2.0', method: 'tools/call', ... });
}

With Pancake:

// With Pancake
const { data } = useViewParams();
const { dispatch } = useAction();
await dispatch('search', { query });

Same code, works everywhere.

Next Steps

MCP Apps Architecture: How MCP apps work
Host-Guest Communication: Communication patterns
Troubleshooting: Debug protocol issues

On this page