Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BookStore MCPfind books about programming under $40"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π BookStore MCP - Complete Setup Guide
π― Project Overview
Full-featured bookstore MCP server vα»i 6 tools vΓ 4 interactive widgets, sα» dα»₯ng Fractal MCP SDK chΓnh thα»ng.
Features:
β 6 MCP Tools: search, detail, cart, checkout, history
β 4 React Widgets: vα»i useWidgetProps, useWidgetState, useLayout, useGlobalContext
β Zod Validation: Type-safe input schemas
β Structured Content: Proper widget props
β Dark/Light Theme: Responsive design
β In-Memory Database: 8 sample books
π¦ Step 1: Create Project
# Create directory
mkdir bookstore-mcp
cd bookstore-mcp
# Initialize npm
npm init -yπ Step 2: Create File Structure
# Create directories
mkdir -p src/ui
mkdir -p src/server
mkdir -p dist/ui
mkdir -p dist/server
# Create files (copy from artifacts)
touch src/server/index.ts
touch src/server/database.ts
touch src/server/types.ts
touch src/ui/BookListWidget.tsx
touch src/ui/BookDetailWidget.tsx
touch src/ui/CartWidget.tsx
touch src/ui/OrderHistoryWidget.tsx
touch package.json
touch tsconfig.jsonSao chΓ©p nα»i dung tα»« cΓ‘c artifacts vΓ o files tΖ°Ζ‘ng α»©ng:
package.json- tα»« artifact "package.json"tsconfig.json- tα»« artifact "tsconfig.json"src/server/types.ts- tα»« artifact "src/server/types.ts"src/server/database.ts- tα»« artifact "src/server/database.ts"src/server/index.ts- tα»« artifact "src/server/index.ts - BookStore MCP Server"src/ui/BookListWidget.tsx- tα»« artifact "src/ui/BookListWidget.tsx"src/ui/BookDetailWidget.tsx- tα»« artifact "src/ui/BookDetailWidget.tsx"src/ui/CartWidget.tsx- tα»« artifact "src/ui/CartWidget.tsx"src/ui/OrderHistoryWidget.tsx- tα»« artifact "src/ui/OrderHistoryWidget.tsx"
π₯ Step 3: Install Dependencies
# Install production dependencies
npm install @fractal-mcp/oai-hooks@latest @fractal-mcp/oai-server@latest zod
# Install dev dependencies
npm install --save-dev \
@fractal-mcp/cli@latest \
@types/node \
@types/react \
@types/react-dom \
react \
react-dom \
typescript \
viteποΈ Step 4: Build Project
# Build React widgets first (creates HTML files)
npm run build:ui
# Build TypeScript server
npm run build:server
# Or build all at once
npm run buildOr if error run
chmod +x fix-widgets.sh
./fix-widgets.shExpected output:
dist/
βββ ui/
β βββ book-list/index.html
β βββ book-detail/index.html
β βββ cart/index.html
β βββ order-history/index.html
βββ server/
βββ index.js
βββ database.js
βββ types.jsπ Step 5: Start Server Locally
npm startExpected console output:
π Starting BookStore MCP Server...
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π BOOKSTORE MCP SERVER β
β Status: β
Running β
β Port: 8000 β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββπ§ͺ Step 6: Test Local Server
Terminal 1 (Server):
npm startTerminal 2 (Test):
# Test health endpoint
curl http://localhost:8000/health
# Open in browser
open http://localhost:8000BαΊ‘n sαΊ½ thαΊ₯y UI vα»i thΓ΄ng tin server!
π Step 7: Deploy to Render
7.1 Push to GitHub
# Initialize git
git init
git add .
git commit -m "Initial commit: BookStore MCP"
# Create repo on GitHub, then:
git remote add origin https://github.com/YOUR_USERNAME/bookstore-mcp.git
git branch -M main
git push -u origin main7.2 Deploy on Render
Truy cαΊp https://render.com
Click "New +" β "Web Service"
Connect GitHub repository
Settings:
Name:
bookstore-mcpEnvironment:
NodeBuild Command:
npm install && npm run buildStart Command:
npm startInstance Type: Free
Click "Create Web Service"
7.3 Get URL
Sau khi deploy xong (3-5 phΓΊt):
https://bookstore-mcp-xxxx.onrender.comTest: Mα» URL trong browser, bαΊ‘n sαΊ½ thαΊ₯y server info page!
π Step 8: Connect to ChatGPT
Method 1: Direct URL (Recommended)
Mα» ChatGPT β Settings (βοΈ)
Click "Apps SDK" (hoαΊ·c "Integrations")
Click "Add App"
NhαΊp URL:
https://bookstore-mcp-xxxx.onrender.comChatGPT sαΊ½ auto-discover MCP endpoint
Click "Connect"
Method 2: MCP Endpoint
NαΊΏu method 1 khΓ΄ng work:
URL:
https://bookstore-mcp-xxxx.onrender.com/mcpTransport: SSE (Server-Sent Events)
No authentication required
π¬ Step 9: Test in ChatGPT
Sau khi connect thΓ nh cΓ΄ng, thα» cΓ‘c lα»nh:
1. "Tìm sÑch vỠProgramming"
2. "TΓ¬m sΓ‘ch TypeScript giΓ‘ dΖ°α»i $50"
3. "Cho tΓ΄i xem chi tiαΊΏt sΓ‘ch cΓ³ ID lΓ 1"
4. "ThΓͺm sΓ‘ch ID 2 vΓ o giα» hΓ ng"
5. "ThΓͺm 3 cuα»n sΓ‘ch ID 3 vΓ o giα»"
6. "Xem giα» hΓ ng cα»§a tΓ΄i"
7. "Thanh toΓ‘n ΔΖ‘n hΓ ng"
8. "Xem lα»ch sα» ΔΖ‘n hΓ ng"ChatGPT sαΊ½:
β Show text response
β Render interactive widget UI
β Widget cΓ³ dark/light theme
β Data update real-time
π Troubleshooting
Issue 1: Build fails
# Clean vΓ rebuild
npm run clean
npm install
npm run buildIssue 2: Widget khΓ΄ng hiα»n thα»
Check:
# Verify widget HTML files exist
ls -la dist/ui/*/index.html
# Should output:
# dist/ui/book-list/index.html
# dist/ui/book-detail/index.html
# dist/ui/cart/index.html
# dist/ui/order-history/index.htmlFix:
npm run build:uiIssue 3: ChatGPT connection failed
Verify endpoints:
curl https://your-app.onrender.com/health
# Should return JSON with status: ok
curl https://your-app.onrender.com/mcp
# Should return SSE streamCommon fixes:
ΔαΊ£m bαΊ£o Render service Δang running (khΓ΄ng sleep)
Check Render logs for errors
Verify PORT env variable (Render auto-sets this)
Issue 4: Module not found errors
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm installπ Architecture
βββββββββββββββ
β ChatGPT β User asks: "TΓ¬m sΓ‘ch TypeScript"
ββββββββ¬βββββββ
β calls MCP tool: search-books
β
βββββββββββββββββββββββ
β MCP Server β
β (src/server) β
β β’ Register tools β
β β’ Process request β
β β’ Return data β
ββββββββ¬βββββββββββββββ
β returns structuredContent
β
βββββββββββββββββββββββ
β React Widget UI β
β (dist/ui/*.html) β
β β’ useWidgetProps() β
β β’ Render UI β
β β’ User interacts β
βββββββββββββββββββββββπ¨ Customization
Add new book:
Edit src/server/database.ts:
{
id: '9',
title: 'Your Book Title',
author: 'Author Name',
price: 39.99,
category: 'Programming',
// ... other fields
}Add new tool:
Edit src/server/index.ts:
registerOpenAIWidget(
server,
{
id: "your-tool",
title: "Your Tool",
// ... config
},
async (args) => {
// Handler logic
}
);Modify widget UI:
Edit src/ui/*.tsx files, then:
npm run build:uiπ Resources
Fractal MCP SDK: https://github.com/fractal-mcp/sdk
OpenAI Apps SDK: https://developers.openai.com/apps-sdk/
Model Context Protocol: https://modelcontextprotocol.io
Render Docs: https://render.com/docs
β Success Checklist
Project created vα»i ΔΓΊng structure
Dependencies installed
Build successful (cΓ³ dist/ui/*/index.html)
Server chαΊ‘y local (port 8000)
Deployed to Render
ChatGPT connected
All 6 tools hoαΊ‘t Δα»ng
Widgets hiα»n thα» ΔΓΊng
Theme switching works
π Done!
BαΊ‘n ΔΓ£ cΓ³ mα»t BookStore MCP Server hoΓ n chα»nh vα»i:
β 6 powerful tools
β 4 beautiful widgets
β Full Fractal MCP SDK features
β ChatGPT integration
β Production-ready code
Next steps:
Add more books to database
Implement user authentication
Add payment processing
Deploy to production domain
Share with community!
Happy coding! ππ
This server cannot be installed
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.