mcpField
M
MCP Stateful Example

MCP Stateful Example

Local
github.com/stevemadereDeveloper Tools1Updated 69w ago
Repository

About MCP Stateful Example

MCP Stateful Example is a minimal server-and-client project for exploring session-based tool calls. It includes test tools and integration tests that check session persistence, making it useful for learning and validating stateful MCP behavior.

Key features

  1. 01Minimal stateful MCP server
  2. 02Session-aware tool invocation
  3. 03`imagine` and `isLessThan` test tools
  4. 04Python integration tests for session persistence
  5. 05`/health` monitoring endpoint

Use cases

  1. 01Learn how MCP sessions retain state
  2. 02Test session-based tool call behavior
  3. 03Validate server health during development

MCP support

The project implements an MCP server with a `POST /mcp` endpoint and includes a test client. Its tools maintain session state for testing.

#mcp#mcp-server#stateful-server

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

No install method listed yet

We haven’t collected a package or remote endpoint for this server. Follow the instructions in the project README.

Repository

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

MCP Stateful Example

A minimal, fully MCP-compliant server and client setup for exploring and validating session-based tool invocation workflows using the Model Context Protocol (MCP).

Features

  • Toy Stateful MCP Server: Implements a minimal MCP server with session handling
  • Test Tools: Includes imagine and isLessThan tools for testing session state
  • Integration Tests: Python-based tests for validating server behavior and session persistence
  • Health Check: Built-in /health endpoint for monitoring server status

Prerequisites

  • Node.js 18+
  • Python 3.8+ (for integration tests)
  • npm or yarn

Getting Started

  1. Clone the repository
  2. Install Node.js dependencies: 
    npm install
  3. Install Python dependencies for integration tests: 
    pip install -r test/integration/requirements.txt
  4. Create a .env.test file in the project root with the following content: 
    PORT=3088
  5. Start the development server: 
    npm run dev

Running Tests

Unit Tests
npm test
Integration Tests
# Run all integration tests
npm run itest

# Or run a specific test
cd test/integration
python test_initialize.py

Project Structure

  • src/ - Source code
    • server/ - MCP server implementation
      • tools/ - Tool definitions
    • client/ - Test client implementation
  • test/ - Test files
    • integration/ - Python-based integration tests
  • scripts/ - Build and utility scripts

Available Tools

imagine

Picks a random number between the specified lower and upper bounds and stores it in the session.

Parameters:

  • lower: Lower bound (inclusive)
  • upper: Upper bound (inclusive)
isLessThan

Checks if a number is less than the previously imagined number in the current session.

Parameters:

  • number: Number to compare against the imagined number

API Endpoints

GET /health

Health check endpoint that returns server status.

POST /mcp

Main MCP protocol endpoint for handling MCP-compliant requests.

Environment Variables

  • PORT: Port number the server will listen on (default: 3000)
  • NODE_ENV: Environment mode (e.g., 'development', 'production')

License

ISC

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.