# 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:
```bash
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](./QUICKSTART.md)** - Get started in 5 minutes
- **[HTTP Streaming Guide](./HTTP-STREAMING-GUIDE.md)** - Complete HTTP Streaming Transport guide
- **[Usage Examples](./EXAMPLES.md)** - Full code examples (Node.js, Python, Browser)
- **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - 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 file
- `read_page_resource`: Read pageResource.md file
## Installation
```bash
npm install
```
## Running Locally
```bash
# 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:
```bash
# 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)
```bash
# First start the server
npm start
# In another terminal, run the test client
npm run test-streaming
```
The test client will:
1. List all available tools
2. Call `read_widget_resource` tool
3. Call `read_page_resource` tool
### Using curl for Local Testing
```bash
# 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**:
```bash
# 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**:
```bash
# 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
```bash
# Local
curl http://localhost:3000/health
# Production
curl https://mcp-demo-d3cj.onrender.com/health
```
### Get Server Information
```bash
# 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:
1. Send HTTP POST requests to the `/mcp` endpoint
2. Use JSON-RPC 2.0 format
3. Include proper Accept headers: `application/json, text/event-stream`
4. Receive results through HTTP response
### Configuration Examples
#### Local Development
```json
{
"mcpServers": {
"mcp-demo-local": {
"transport": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
}
```
#### Production
```json
{
"mcpServers": {
"mcp-demo": {
"transport": {
"type": "http",
"url": "https://mcp-demo-d3cj.onrender.com/mcp"
}
}
}
}
```
### Using MCP SDK
```typescript
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)
```bash
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:
```bash
npm run dev
```
## Deployment
This server is deployed on [Render](https://render.com) and available at:
**https://mcp-demo-d3cj.onrender.com/mcp**
You can deploy your own instance:
1. Fork this repository
2. Connect to Render/Vercel/Railway
3. Set environment variables if needed
4. Deploy!
## License
MIT
