How do I use Custom MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Custom MCP Server calculate 25 \* 4 + 15" 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.

Custom MCP Server 🤖

A Model Context Protocol (MCP) server built with Next.js, providing useful tools and utilities through both HTTP and Server-Sent Events (SSE) transports.

🚀 Features

🔧 Available Tools

echo - Echo any message back (perfect for testing)
get-current-time - Get the current timestamp and ISO date
calculate - Perform basic mathematical calculations safely

🌐 Transport Methods

HTTP Transport (/mcp) - Stateless HTTP requests (works without Redis)
SSE Transport (/sse) - Server-Sent Events with Redis for state management

🔒 Security Features

Rate limiting (100 requests per minute)
Safe mathematical expression evaluation
Input sanitization and validation

🏃‍♂️ Quick Start

Prerequisites

Node.js 18+
npm or yarn
Docker (optional, for local Redis)

Setup

Clone and install dependencies:
npm install
Run the automated setup:
npm run setup
This will:
- Create environment configuration
- Set up Redis (Docker) if available
- Start the development server automatically
Manual start (alternative):
npm run dev

The server will be available at http://localhost:3000

🧪 Testing

Quick Tests

# Test HTTP transport npm run test:http # Test SSE transport (requires Redis) npm run test:sse # Test with Claude Desktop protocol npm run test:stdio # Comprehensive tool testing npm run test:tools

Manual Testing

You can test the MCP server manually using curl:

# List available tools curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }' # Call the echo tool curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "echo", "arguments": { "message": "Hello World!" } } }' # Calculate an expression curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "calculate", "arguments": { "expression": "15 * 4 + 10" } } }'

🔧 Configuration

Environment Variables

Create a .env.local file:

# Local Redis (Docker) REDIS_URL=redis://localhost:6379 # Upstash Redis (Production) UPSTASH_REDIS_REST_URL=your-upstash-url UPSTASH_REDIS_REST_TOKEN=your-upstash-token

Redis Setup

The server automatically detects and uses Redis in this priority order:

Upstash Redis (if UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are set)
Local Redis (if REDIS_URL is set)
No Redis (HTTP transport only)

Local Redis with Docker

# The setup script handles this automatically, but you can also run manually: docker run -d --name redis-mcp -p 6379:6379 redis:alpine

Upstash Redis (Recommended for Production)

Create an Upstash Redis database at upstash.com
Add the connection details to your .env.local
The server will automatically detect and use it

🖥️ Integration with AI Tools

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{ "mcpServers": { "custom-mcp": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:3000/mcp" ] } } }

Configuration file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor IDE

For Cursor 0.48.0 or later (direct SSE support):

{ "mcpServers": { "custom-mcp": { "url": "http://localhost:3000/sse" } } }

For older Cursor versions:

{ "mcpServers": { "custom-mcp": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:3000/mcp" ] } } }

🛠️ Development

Project Structure

custom-mcp-server/ ├── app/ │ ├── [transport]/ │ │ └── route.ts # Main MCP server logic │ ├── layout.tsx # Root layout │ └── page.tsx # Home page ├── lib/ │ └── redis.ts # Redis utilities ├── scripts/ │ ├── setup.mjs # Automated setup │ ├── test-http-client.mjs # HTTP transport tests │ ├── test-sse-client.mjs # SSE transport tests │ └── test-tools.mjs # Comprehensive tool tests ├── package.json ├── next.config.ts └── README.md

Adding New Tools

Define the tool in app/[transport]/route.ts:

const tools = { // ... existing tools myNewTool: { name: "my-new-tool", description: "Description of what your tool does", inputSchema: { type: "object", properties: { param1: { type: "string", description: "Description of parameter" } }, required: ["param1"] } } };

Add the handler:

const toolHandlers = { // ... existing handlers "my-new-tool": async ({ param1 }: { param1: string }) => { // Your tool logic here return { content: [ { type: "text", text: `Result: ${param1}` } ] }; } };

Testing Your Changes

# Run all tests npm run test:tools # Test specific functionality npm run test:http npm run test:sse

📝 API Reference

Tools/List

Get all available tools:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Tools/Call

Call a specific tool:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "tool-name", "arguments": { "param": "value" } } }

🚀 Deployment

Vercel (Recommended)

Deploy to Vercel:
vercel
Add environment variables in Vercel dashboard:
- UPSTASH_REDIS_REST_URL
- UPSTASH_REDIS_REST_TOKEN
Update your AI tool configurations to use the deployed URL:
https://your-app.vercel.app/mcp https://your-app.vercel.app/sse

Other Platforms

The server is a standard Next.js application and can be deployed to any platform that supports Node.js:

Netlify
Railway
Render
DigitalOcean App Platform

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/my-new-feature
Make your changes and add tests
Run the test suite: npm run test:tools
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature/my-new-feature
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Troubleshooting

Common Issues

Server not starting:

Check if port 3000 is available
Ensure all dependencies are installed: npm install

Redis connection issues:

Verify Docker is running: docker ps
Check Redis container status: docker ps -a | grep redis-mcp
Restart Redis: docker restart redis-mcp

AI tool not detecting server:

Ensure the server is running and accessible
Check the configuration file syntax (valid JSON)
Restart your AI tool after configuration changes
Verify the server URL is correct

Tool calls failing:

Check server logs for error messages
Test tools manually with npm run test:tools
Verify the tool parameters match the expected schema

Debug Mode

Enable debug logging by setting the environment variable:

DEBUG=1 npm run dev

📞 Support

Create an issue on GitHub for bug reports
Check existing issues for common problems
Review the test scripts for usage examples

Custom MCP Server