Number Guessing Game MCP Server

What is Number Guessing Game MCP Server?

A demonstration Model Context Protocol (MCP) server built in TypeScript that hosts a simple number guessing game. It showcases a dynamic, session-based architecture where each connecting user receives their own isolated set of tools and resources managed by a central Express.js controller. Designed as a learning resource and practical example for building dynamic, multi-user MCP applications.

How to use Number Guessing Game MCP Server?

Run the server locally via npm run dev (development) or npm start (production). Clients must support OAuth2 with dynamic client registration, tool notifications, and resource notifications. The live server is accessible at https://mcp.number-guessing-game.portal.one/mcp. For local access, use http://localhost:8083/mcp or expose with ngrok.

Key features of Number Guessing Game MCP Server

• True multi‑user sessions with isolated game state per user.
• Dynamic MCP tools (start_game, guess_number, give_up) enabled/disabled per user based on game state.
• Dynamic MCP resource (game_state) created and destroyed per session.
• Firestore integration for persistent game state and high scores.
• Clean, scalable architecture with state pattern (Lobby, Playing) and lifecycle management.

Use cases of Number Guessing Game MCP Server

• Learning how to build dynamic, session‑scoped MCP servers with TypeScript.
• Demonstrating stateful user sessions over a stateless HTTP transport.
• Showcasing Firestore‑backed MCP tools and resources that scale horizontally.

FAQ from Number Guessing Game MCP Server

What clients support this server?

Clients must support OAuth2 (with dynamic client registration), tool notifications, and resource notifications. The Portal One web client and MCP Inspector are mentioned as compatible options.

What runtime does the server require?

Node.js v18.x or later, with npm or yarn. Google Cloud Firestore access is needed for state persistence.

How are tools and resources managed per user?

A central Express.js controller creates a unique set of MCP tools and resources for each user upon session initialization and destroys them on close, using transport lifecycle hooks (onsessioninitialized, onclose).

Where is game state stored?

Game state and high scores are persisted in Google Cloud Firestore, making the server stateless and horizontally scalable.

What transport does the server use?

It uses StreamableHTTPServerTransport to handle incoming requests at the /mcp endpoint.