BotDojo LogoInteractive Agent SDKBeta
About BotDojoBotDojo

MCP Apps in Headless Mode

Learn how to use MCP Apps with the headless chat components for full control over your UI.

What is Headless Mode?

Headless mode gives you access to the underlying chat and MCP App functionality without the pre-built UI. This is useful when you want to:

  • Build a custom chat interface with your own design
  • Render MCP Apps in specific locations in your UI
  • Control when and how MCP Apps are displayed
  • Integrate chat functionality into an existing application

See it in action: Check out the Headless Chat example and Headless MCP example

Working with BotDojoChatProvider

When using the headless chat components with BotDojoChatProvider, MCP App data (HTML, arguments, results) is automatically managed for you:

📄Complete Example with Providertypescript
1import { BotDojoChatProvider, McpAppHost } from '@botdojo/chat-sdk/headless';
2

3function MyApp() {
4  return (
5    <BotDojoChatProvider
6      apiKey="your-api-key"
7      baseUrl="https://embed.botdojo.com"
8      modelContext={myModelContext}
9      cacheKey="user-123-flow-abc"  // Unique ID for your agent/flow instance
10    >
11      <MyCustomChatUI />
12    </BotDojoChatProvider>
13  );
14}
15

16function MyCustomChatUI() {
17  const [mcpApps, setMcpApps] = useState<string[]>([]);
18

19  return (
20    <div>
21      {/* Your custom chat messages UI */}
22      <div>
23        {/* Render messages... */}
24      </div>
25

26      {/* Render MCP Apps */}
27      {mcpApps.map(appId => (
28        <McpAppHost
29          key={appId}
30          mcpAppId={appId}
31          onOpenLink={(url) => window.open(url, '_blank')}
32          onToolCall={async (tool, params) => {
33            // Handle tool calls
34            return { success: true };
35          }}
36        />
37      ))}
38    </div>
39  );
40}

Caching: The cacheKey is a unique identifier for your agent or flow instance. It's combined with the MCP App resource URI to create a unique cache entry, preventing MCP App HTML from being fetched repeatedly.