polymcp-sdk-mcp-apps is a focused TypeScript SDK for building MCP-style apps with:
- typed tools
- HTML UI resources (
app://...) - HTTP endpoints for tool/resource discovery and execution
Version: 1.3.6
Use this package when you want to ship app-like workflows where an LLM can:
- discover tools (
/list_tools) - call tools (
/tools/{toolName}) - render UI resources (
/list_resources,/resources/{uri})
This is ideal for support hubs, operations dashboards, dispatch centers, and internal copilots.
Requirements:
- Node.js 18+
npm installRun the minimal app:
npm run example:quickstartThen test:
curl http://127.0.0.1:3200/list_tools
curl http://127.0.0.1:3200/list_resources
curl http://127.0.0.1:3200/resources/app%3A%2F%2Fcounter-app%2Fui%2Fcounter-uiBase URL example: http://127.0.0.1:3200
GET /server infoGET /appsregistered apps summaryGET /list_toolstool catalog for LLM tool-callingGET /list_resourcesUI/resource catalogGET /resources/{encoded_uri}fetch resource contentPOST /tools/{toolName}execute one toolPOST /invoke/{toolName}legacy compatibilityPOST /invokelegacy body format{ "tool": "...", "parameters": { ... } }
import { MCPAppBuilder, MCPAppsSDKServer } from 'polymcp-sdk-mcp-apps';
const app = new MCPAppBuilder({
id: 'support-hub',
name: 'Support Hub',
description: 'Ticket triage and operations',
})
.addTool({
name: 'create_ticket',
description: 'Create a support ticket',
inputSchema: {
type: 'object',
required: ['subject'],
properties: { subject: { type: 'string' } },
},
handler: async ({ subject }) => ({ ok: true, subject }),
})
.addHTMLUI({
name: 'Support UI',
html: '<html><body><h2>Support Hub</h2></body></html>',
})
.build();
const server = new MCPAppsSDKServer({ port: 3200, enableCORS: true });
server.register(app);
await server.start();This repo includes a runnable OpenAI bridge:
# Terminal 1
npm run example:quickstart
# Terminal 2
export OPENAI_API_KEY=...
export OPENAI_MODEL=gpt-4o-mini
# Optional if your app runs on a different port
export MCP_APPS_BASE_URL=http://127.0.0.1:3200
# Optional if your SDK server uses apiKey protection
export MCP_APPS_API_KEY=...
npm run example:gpt-bridge -- "Get the current counter and summarize it in one sentence."How it works:
- Reads tools from
/list_tools - Registers them as GPT function tools
- Executes requested tool calls via
/tools/{toolName} - Sends tool results back to the model until final answer
This repo also includes a runnable Claude bridge:
# Terminal 1
npm run example:quickstart
# Terminal 2
export ANTHROPIC_API_KEY=...
export ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
export MCP_APPS_BASE_URL=http://127.0.0.1:3200
# Optional if your SDK server uses apiKey protection
export MCP_APPS_API_KEY=...
npm run example:claude-bridge -- "Use available tools to check the counter and report the value."How it works:
- Reads tools from
/list_tools - Sends them in
toolsto Anthropic Messages API - Executes
tool_userequests via/tools/{toolName} - Returns
tool_resultblocks until Claude returns final text
Start any app server and connect Inspector to that base URL.
In Resources tab, open the app://... resource URI.
Inspector injects the tool bridge so UI actions can call /tools/... and refresh live.
npm run example:support-hub
npm run example:ecommerce-ops
npm run example:field-dispatch- support-hub (
http://127.0.0.1:3201): ticket intake, triage, status flow, KB search - ecommerce-ops (
http://127.0.0.1:3202): order ingestion, shipment updates, revenue summary - field-dispatch (
http://127.0.0.1:3203): work orders, lifecycle transitions, SLA risk
All examples persist state in examples/data/*.json.
Protect server endpoints with API key:
const server = new MCPAppsSDKServer({
port: 3200,
apiKey: process.env.MCP_APPS_API_KEY,
allowedOrigins: ['http://localhost:3000'],
});When enabled, clients can authenticate with:
- header
X-API-Key: <key> - or
Authorization: Bearer <key>
401 Unauthorized- Set
MCP_APPS_API_KEYin bridge scripts when server usesapiKey.
- Set
Tool not found- Check exact tool names from
GET /list_tools.
- Check exact tool names from
CORS blocked- Add your frontend origin to
allowedOrigins.
- Add your frontend origin to
No tools available- Verify app registration (
server.register(app)) and endpoint health (GET /list_tools).
- Verify app registration (
- Put TLS and auth policy behind a reverse proxy
- Enable strict CORS allowlist
- Log tool execution for auditability
- Add domain-level validation and rate limiting