Hello Service MCP Server

Hello Service

A unified HTTP/HTTPS service built with Bun that provides both REST API endpoints and MCP (Model Context Protocol) functionality over SSE (Server-Sent Events).

Architecture

This service combines traditional REST API functionality with MCP capabilities in a single TypeScript/Bun server (server.ts). The MCP protocol, typically used for stdio communication between AI assistants and tools, is exposed through HTTP endpoints for remote access.

Key Components:

Bun Runtime: Fast JavaScript/TypeScript runtime for server-side applications
HTTP/HTTPS Server: Built-in Bun server with CORS support
MCP Integration: Model Context Protocol tools exposed via SSE (Server-Sent Events)
Systemd Integration: Production deployment with automatic restart and logging

Features

HTTP and HTTPS support
CORS enabled for all origins
REST API endpoints
MCP tools exposed via SSE transport
Health check endpoint
Systemd service integration
TypeScript support
Fast startup and low memory footprint

API Endpoints

Standard API

GET /hello - Returns a JSON greeting message
GET /health - Health check endpoint
GET /info - Server capabilities and endpoints information

MCP-over-SSE API

GET /sse - SSE endpoint for MCP connections
POST /messages?sessionId=XXX - Send MCP protocol messages

Installation

Prerequisites

Install Bun if not already installed:

curl -fsSL https://bun.sh/install | bash

Clone the repository:

git clone <repository-url>
cd hello-service-workspace

Install dependencies:

bun install

Running the Server

Development Mode

Run directly from the current directory:

# Run with default settings (HTTP on port 3000)
bun server.ts

# Or using npm
npm start

# Run with custom port
PORT=8080 bun server.ts

# Run with HTTPS
SSL_KEY_PATH=certs/server.key SSL_CERT_PATH=certs/server.crt bun server.ts

Production Deployment

1. Prepare the System

Create a dedicated user for the service:

sudo useradd -r -s /bin/false hello-service

2. Deploy to /opt

# Create deployment directory
sudo mkdir -p /opt/hello-service

# Copy application files
sudo cp server.ts package.json package-lock.json /opt/hello-service/

# Set ownership
sudo chown -R hello-service:hello-service /opt/hello-service

# Install dependencies
sudo -u hello-service bash -c "cd /opt/hello-service && bun install"

3. Install Systemd Service

# Copy service file
sudo cp hello-service.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable hello-service

# Start the service
sudo systemctl start hello-service

4. Verify Deployment

# Check service status
sudo systemctl status hello-service

# Test the API
curl http://localhost:3000/info | jq .

# View logs
sudo journalctl -u hello-service -f

Using the MCP Server

MCP Tools Available

The server provides the following MCP tool:

hello - Returns a greeting message with optional name parameter

Connecting with Claude Desktop

To use this MCP server with Claude Desktop, see the detailed setup guide: CLAUDE_DESKTOP_SETUP.md

Quick configuration example:

{
  "mcpServers": {
    "hello-service": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://91.99.172.64:3000/sse"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

This configuration uses npx to run mcp-remote, which acts as a proxy between Claude Desktop's stdio transport and remote SSE servers.

Alternative: Direct SSE Connection Test

# Connect to SSE endpoint
curl -N -H "Accept: text/event-stream" https://91.99.172.64:3000/sse

# The server will respond with a session ID event

Configuration

Environment Variables

PORT - Server port (default: 3000)
SSL_KEY_PATH - Path to SSL private key file (for HTTPS)
SSL_CERT_PATH - Path to SSL certificate file (for HTTPS)
NODE_ENV - Environment mode (automatically set to "production" by systemd)

HTTPS Setup

Generate self-signed certificates (for development):

mkdir -p certs
cd certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout server.key -out server.crt \
  -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"
cd ..

For production with systemd, place certificates in /opt/hello-service/certs/ and update the service:

sudo systemctl edit hello-service

Add:

[Service]
Environment="SSL_KEY_PATH=/opt/hello-service/certs/server.key"
Environment="SSL_CERT_PATH=/opt/hello-service/certs/server.crt"

Service Management

Systemd Commands

# Start/Stop/Restart
sudo systemctl start hello-service
sudo systemctl stop hello-service
sudo systemctl restart hello-service

# Enable/Disable auto-start
sudo systemctl enable hello-service
sudo systemctl disable hello-service

# Check status
sudo systemctl status hello-service

# View logs
sudo journalctl -u hello-service -n 50     # Last 50 lines
sudo journalctl -u hello-service -f        # Follow logs
sudo journalctl -u hello-service --since "1 hour ago"

Updating the Service

To deploy updates:

# Pull latest changes
git pull

# Copy updated files
sudo cp server.ts package.json /opt/hello-service/

# Update dependencies if needed
sudo -u hello-service bash -c "cd /opt/hello-service && bun install"

# Restart service
sudo systemctl restart hello-service

Testing

Quick Tests

# Test API endpoints
curl http://localhost:3000/hello | jq .
curl http://localhost:3000/health | jq .
curl http://localhost:3000/info | jq .

# Test SSE connection
curl -N http://localhost:3000/sse

Using HTTPie (if installed)

# GET requests
http :3000/info
http :3000/hello
http :3000/health

Troubleshooting

Service Won't Start

Check logs for errors:

sudo journalctl -u hello-service -n 100 --no-pager

Verify Bun is installed and accessible:

which bun
bun --version

Check file permissions:

ls -la /opt/hello-service/

Test manually as service user:

sudo -u hello-service bash -c "cd /opt/hello-service && bun server.ts"

Port Already in Use

If you see EADDRINUSE error:

# Find process using port 3000
sudo lsof -i :3000

# Or change the port
sudo systemctl edit hello-service
# Add: Environment="PORT=3001"

Dependencies Issues

# Reinstall dependencies
sudo rm -rf /opt/hello-service/node_modules
sudo -u hello-service bash -c "cd /opt/hello-service && bun install"

Development Tools

The following tools are installed on the server for development and debugging:

jq - Command-line JSON processor
yq - Command-line YAML processor
httpie - User-friendly HTTP client
ripgrep (rg) - Fast text search
bat - Cat clone with syntax highlighting
fd - Fast file finder
tree - Directory structure viewer
htop - Interactive process viewer
ncdu - Disk usage analyzer

Security Considerations

The service runs as a dedicated non-privileged user (hello-service)
Systemd security settings restrict file system access
CORS is enabled for all origins (adjust for production)
Consider using a reverse proxy (nginx/caddy) for production
Use proper SSL certificates from Let's Encrypt for production

Contributing

Fork the repository
Create a feature branch
Make your changes
Test locally and with systemd
Submit a pull request

License

[Specify your license here]

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A unified HTTP/HTTPS service that exposes Model Context Protocol (MCP) functionality over HTTP endpoints, allowing clients to list available tools and call them through a standardized API.

Related MCP Servers

MCP-OpenAPI
rmasters
-
security
A
license
-
quality
An MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.
Last updated -
8
Python
MIT License
MCP Gateway
Timandes
-
security
A
license
-
quality
A server that translates Model Context Protocol (MCP) tool callings to traditional HTTP API requests, allowing existing HTTP APIs to be integrated into MCP territory through configurable mappings.
Last updated -
1
Python
Apache 2.0
AgentModeofficial
agentmode
A
security
F
license
A
quality
An all-in-one Model Context Protocol (MCP) server that connects your coding AI to numerous databases, data warehouses, data pipelines, and cloud services, streamlining development workflow through seamless integrations.
Last updated -
2
Python
MCP REST API Server
vinaykp
-
security
F
license
-
quality
A server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.
Last updated -
Python

View all related MCP servers