MCP Apps SDK

Open-source SDK for building applications with the Model Context Protocol (MCP) that is compatible with OpenAI Apps SDK.

This SDK is useful for two types of developers:

• Agent developers who want to integrate MCP-based App UI into their own agents
• MCP App developers who are developing MCP-based Apps that can be integrated with ChatGPT and other agents

Demo Video

Exploring.the.MCP.Apps.SDK.and.Its.Integration.with.AI.Applications.mp4

Installation

Get started quickly with a single command:

npm install @xalia/mcp-apps-sdk

This installs everything you need to build MCP-powered applications! ✨

What's Included

• MCP Client - Connect to and communicate with MCP servers
• Adapters - Integrate with popular AI frameworks (OpenAI, Vercel AI SDK)
• Widget Components - React components for rendering MCP app interfaces

Alternative: Modular Installation

For advanced users who want smaller bundle sizes, install only what you need:

# For agent developers - render MCP app widgets only
npm install @xalia/mcp-apps-widget

# For MCP app developers - client and adapters only
npm install @xalia/mcp-client @xalia/mcp-apps-adapters

Packages

This monorepo contains four packages:

@xalia/mcp-apps-sdk ⭐

Complete SDK - Unified package with everything you need. Install this for the simplest setup.

@xalia/mcp-apps-widget

React components and utilities for rendering MCP app widgets in secure iframes with PostMessage communication.

@xalia/mcp-client

TypeScript client for connecting to and interacting with MCP servers, including tool discovery and execution.

@xalia/mcp-apps-adapters

Adapters for integrating MCP tools with popular AI frameworks like Vercel AI SDK and OpenAI.

Quick Start

Prerequisites

• Node.js 18+
• pnpm 10+
• An MCP server running (default: http://localhost:8002/mcp)

Installation

# Clone the repository with submodules
git clone --recurse-submodules https://github.com/general-intelligence-labs/mcp-apps-sdk.git
cd mcp-apps-sdk

# Or if you already cloned without submodules
git submodule update --init --recursive

# Install dependencies
pnpm install

# Build all packages
pnpm build

Run the Example

The chatbot example requires an MCP server and a static file server for widgets. See examples/chatbot/README.md for detailed setup instructions.

Quick start:

# Terminal 1: Start static file server
cd examples/openai-apps-sdk-examples
pnpm install && pnpm build
pnpm run serve  # Serves on port 4444

# Terminal 2: Start MCP server
cd examples/openai-apps-sdk-examples/solar-system_server_python
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --port 8002

# Terminal 3: Start the chatbot
cd examples/chatbot
pnpm dev

Open http://localhost:3000 to see the chatbot with MCP tool integration.

Development

Project Structure

mcp-apps-sdk/
├── packages/
│   ├── mcp-apps-sdk/             # ⭐ Complete SDK (umbrella package)
│   ├── mcp-apps-widget/          # Widget rendering components
│   ├── mcp-client/               # MCP protocol client
│   └── mcp-apps-adapters/        # AI framework adapters
├── examples/
│   ├── chatbot/                  # Example Next.js chatbot app
│   └── openai-apps-sdk-examples/ # OpenAI SDK examples (git submodule)
└── package.json                  # Root package.json

Available Scripts

# Build all packages
pnpm build

# Run all packages in development mode
pnpm dev

# Run tests
pnpm test

# Lint code
pnpm lint

# Clean all build artifacts
pnpm clean

📚 Usage

Simple Import (Recommended)

Install the complete SDK and import everything from one place:

npm install @xalia/mcp-apps-sdk

import { 
  createMCPClient, 
  connectMCPClient,
  createVercelAITools,
  AssistantAppEmbed 
} from '@xalia/mcp-apps-sdk';

// Connect to MCP server
const client = await createMCPClient({ name: 'my-app', version: '1.0.0' });
await connectMCPClient(client, transport);

// Convert MCP tools for use with AI SDKs
const tools = await createVercelAITools(client);

Modular Imports (For Optimized Bundle Size)

Use specific entry points when you need fine-grained control:

// Client only
import { createMCPClient } from '@xalia/mcp-apps-sdk/client';

// Adapters
import { createOpenAIFunctions } from '@xalia/mcp-apps-sdk/adapters/openai';
import { createVercelAITools } from '@xalia/mcp-apps-sdk/adapters/vercel';

// Widget components
import { AssistantAppEmbed } from '@xalia/mcp-apps-sdk/widget';

For Agent Developers

If you only need to render MCP app widgets:

npm install @xalia/mcp-apps-widget

import { AssistantAppEmbed } from '@xalia/mcp-apps-widget';

function MyApp() {
  return (
    <AssistantAppEmbed
      widgetHtml={widgetHtml}
      toolOutput={result}
      metadata={metadata}
    />
  );
}

Community

Join our Discord community for discussions, support, and updates:

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE for details.

External Resources

• OpenAI Apps SDK Documentation
• Model Context Protocol (MCP)