Example

This MCP server implements a Streamable HTTP transport with JSON-RPC and Server-Sent Events (SSE). Clients create a session and then invoke tools within that session, allowing progress notifications for long-running tasks. Available tools include hello_world (simple greeting), get_server_info (returns server metadata), long_running_test (configurable duration with progress updates), and slow_test (a longer, progress-enabled operation). Use the POST /mcp endpoint to send JSON-RPC requests to call tools, and GET /mcp for SSE streams to receive updates within an active session. Sessions persist across requests, and transports are reused within a session for efficiency. Your client should handle session IDs and terminate them with DELETE /mcp when you’re done.

Prerequisites:

• Node.js (v14+ recommended) and npm
• Basic familiarity with npm scripts used by the project

1. Clone the repository

• git clone https://github.com/danny-avila-example-mcp-server.git
• cd danny-avila-example-mcp-server

2. Install dependencies

• npm ci

3. Configure environment (optional)

• PORT: port to run the server on (default 3001)
• DEBUG: true to enable debug logging (default true)

4. Start the server

• npm run start

5. Development mode (auto-reload)

• npm run dev

6. Run tests (optional)

• npm run test:http

Note: The server exposes endpoints at /mcp for JSON-RPC and SSE, and /health for health checks.

Tips and notes:

• Ensure PORT is not in use by another process. The default is 3001.
• Sessions are created on initialization requests and must be terminated with DELETE /mcp when done.
• Long-running tools (long_running_test, slow_test) emit progress notifications via the notifications/progress event structure. Make sure your client subscription handles SSE if you’re using streaming.
• If you encounter JSON-RPC errors, check that the tool name is correct and arguments match what the server expects (duration, steps, messages, etc.).
• SSE streaming requires a persistent connection; use GET /mcp to subscribe to the event stream within an active session.