MCP Stateful Example

@stevemadere

About MCP Stateful Example

A simple stateful mcp server example. Clone and modify to make any stateful mcp server.

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "mcp-stateful-example": {
      "command": "python",
      "args": [
        "test_initialize.py"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is 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.

How to use MCP Stateful Example?

Clone the repository, install Node.js dependencies with npm install and Python dependencies for integration tests with pip install -r test/integration/requirements.txt. Create a .env.test file with PORT=3088, then start the development server with npm run dev.

Key features of MCP Stateful Example

Implements a minimal MCP server with session handling
Includes imagine and isLessThan test tools
Python‑based integration tests for validating server behavior
Built‑in /health endpoint for monitoring server status

Use cases of MCP Stateful Example

Learning how session state works in MCP tool invocations
Testing and validating MCP client‑server communication
Prototyping stateful tool workflows before building production servers

FAQ from MCP Stateful Example

What tools are available?

Two tools: imagine picks a random number between specified bounds and stores it in the session; isLessThan checks if a number is less than the previously imagined number in the current session.

What are the prerequisites?

Node.js 18+, Python 3.8+ for integration tests, and npm or yarn.

How do I run integration tests?

Use npm run itest from the project root, or run a specific test by navigating to test/integration and executing python test_initialize.py.

What environment variables are used?

PORT (default: 3000) for the server port, and NODE_ENV for the environment mode (e.g., 'development' or 'production').

Does the server have a health check?

Yes, a GET /health endpoint returns server status.

Frequently asked questions

What tools are available?

Two tools: `imagine` picks a random number between specified bounds and stores it in the session; `isLessThan` checks if a number is less than the previously imagined number in the current session.

What are the prerequisites?

Node.js 18+, Python 3.8+ for integration tests, and npm or yarn.

How do I run integration tests?

Use `npm run itest` from the project root, or run a specific test by navigating to `test/integration` and executing `python test_initialize.py`.

What environment variables are used?

`PORT` (default: 3000) for the server port, and `NODE_ENV` for the environment mode (e.g., 'development' or 'production').

Does the server have a health check?

Yes, a `GET /health` endpoint returns server status.

Comments

Basic information

More Other MCP servers

MCP Go 🚀

mark3labs

A Go implementation of the Model Context Protocol (MCP), enabling seamless integration between LLM applications and external data sources and tools.

8.9K

MCP Toolbox for Databases

googleapis

MCP Toolbox for Databases is an open source MCP server for databases.

15.9K

Figs, Relationship Expert

Figs O'Sullivan, LMFT

Couples therapist Figs O'Sullivan (LMFT, 17 years, endorsed by Sue Johnson, creator of EFT) inside your AI. Ask relationship questions answered from his clinical writing, name the pattern in a fight, get a three-step rep

Reactive Resume

amruthpillai

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5K

IDA Pro MCP

mrexodia

AI-powered reverse engineering assistant that bridges IDA Pro with language models through MCP.

9.9K