MCP Demo Server
A stateless HTTP Streaming server built with Model Context Protocol (MCP) and Express.
🌐 Live Demo
Production URL: https://mcp-demo-d3cj.onrender.com/mcp
Try it now:
curl -X POST https://mcp-demo-d3cj.onrender.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
📚 Documentation
- Quick Start Guide - Get started in 5 minutes
- HTTP Streaming Guide - Complete HTTP Streaming Transport guide
- Usage Examples - Full code examples (Node.js, Python, Browser)
- Troubleshooting Guide - Common issues and solutions
Features
- ✅ Fully Stateless - Each request is processed independently
- ✅ HTTP Streaming - Standard HTTP POST-based streaming transport
- ✅ Easy to Scale - No session management, horizontally scalable
- ✅ Simple Deployment - Perfect for serverless environments (Lambda, Cloud Functions)
- ✅ Production Ready - Live at https://mcp-demo-d3cj.onrender.com
- ✅ Two built-in tools:
read_widget_resource: Read widgetResource.md fileread_page_resource: Read pageResource.md file
Installation
npm install
Running Locally
# Production mode
npm start
# Development mode (with hot reload)
npm run dev
# Test with MCP Inspector
npm run test
Server runs on http://localhost:3000 by default.
Testing and Debugging
Using Production Server
Test the live production server:
# List available tools
curl -X POST https://mcp-demo-d3cj.onrender.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# Call read_widget_resource tool
curl -X POST https://mcp-demo-d3cj.onrender.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_widget_resource","arguments":{}}}'
Using HTTP Streaming Test Client (Recommended)
# First start the server
npm start
# In another terminal, run the test client
npm run test-streaming
The test client will:
- List all available tools
- Call
read_widget_resourcetool - Call
read_page_resourcetool
Using curl for Local Testing
# List available tools
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# Call read_widget_resource tool
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_widget_resource","arguments":{}}}'
# Check server health
curl http://localhost:3000/health
# Get server information
curl http://localhost:3000/
API Endpoints
HTTP Streaming Transport
1. MCP Endpoint
- Path:
/mcp - Method: POST
- Description: HTTP streaming endpoint for MCP JSON-RPC requests
- Features: Fully stateless, each request is processed independently
Other Endpoints
2. Health Check
- Path:
/health - Method: GET
- Description: Check server status
3. Root Path
- Path:
/ - Method: GET
- Description: Get server information and available tools list
Available Tools
read_widget_resource
Reads the content of src/resources/widgetResource.md file.
Input: No parameters required
Output: File content as text
Example:
# Local
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_widget_resource","arguments":{}}}'
# Production
curl -X POST https://mcp-demo-d3cj.onrender.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_widget_resource","arguments":{}}}'
read_page_resource
Reads the content of src/resources/pageResource.md file.
Input: No parameters required
Output: File content as text
Example:
# Local
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_page_resource","arguments":{}}}'
# Production
curl -X POST https://mcp-demo-d3cj.onrender.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_page_resource","arguments":{}}}'
Usage Examples
Check Server Health
# Local
curl http://localhost:3000/health
# Production
curl https://mcp-demo-d3cj.onrender.com/health
Get Server Information
# Local
curl http://localhost:3000/
# Production
curl https://mcp-demo-d3cj.onrender.com/
MCP Client Integration
To connect to this MCP server, your MCP client needs to:
- Send HTTP POST requests to the
/mcpendpoint - Use JSON-RPC 2.0 format
- Include proper Accept headers:
application/json, text/event-stream - Receive results through HTTP response
Configuration Examples
Local Development
{
"mcpServers": {
"mcp-demo-local": {
"transport": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
}
Production
{
"mcpServers": {
"mcp-demo": {
"transport": {
"type": "http",
"url": "https://mcp-demo-d3cj.onrender.com/mcp"
}
}
}
}
Using MCP SDK
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({
name: 'my-client',
version: '1.0.0',
});
// Use production server
const transport = new StreamableHTTPClientTransport(
new URL('https://mcp-demo-d3cj.onrender.com/mcp')
);
// Or use local server
// const transport = new StreamableHTTPClientTransport(
// new URL('http://localhost:3000/mcp')
// );
await client.connect(transport);
// List tools
const tools = await client.listTools();
// Call tool
const result = await client.callTool({
name: 'read_widget_resource',
arguments: {},
});
Tech Stack
- @modelcontextprotocol/sdk: MCP protocol implementation
- Express: Web framework
- CORS: Cross-Origin Resource Sharing support
- Node.js: ES Modules
Project Structure
mcp-demo/
├── src/
│ ├── index.js # Main server file
│ └── resources/
│ ├── widgetResource.md # Widget resource file
│ └── pageResource.md # Page resource file
├── test-http-streaming.js # HTTP Streaming test client
├── package.json
├── README.md
└── LICENSE
Environment Variables
PORT: Server port (default: 3000)
PORT=8080 npm start
Development
The server uses ES Modules and requires Node.js 14.0 or higher.
In development mode, use the --watch flag for automatic restarts:
npm run dev
Deployment
This server is deployed on Render and available at: https://mcp-demo-d3cj.onrender.com/mcp
You can deploy your own instance:
- Fork this repository
- Connect to Render/Vercel/Railway
- Set environment variables if needed
- Deploy!
License
MIT