Skip to main content
Glama

Agent State MCP Server

A Model Context Protocol (MCP) server built with FastMCP that provides agent state and log management tools for long-lived agents that may be interrupted and resumed.

Features

  • State management tools for tracking agent progress

  • Log management tools for maintaining append-only event history

  • Built with FastMCP for easy MCP server development

  • Type-safe Python code with proper type hints

Related MCP server: joa

Setup

Prerequisites

  • Python 3.14+

  • uv package manager

Installation

  1. Install dependencies:

    uv sync
  2. Activate the virtual environment (if needed):

    source .venv/bin/activate  # On macOS/Linux
    # or
    .venv\Scripts\activate  # On Windows

Running the Server

Run the MCP server:

uv run python main.py

Setting up MCP in Claude Desktop

  1. Open Claude Desktop settings:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the MCP server configuration:

    {
      "mcpServers": {
        "agent-state": {
          "command": "uv",
          "args": [
            "run",
            "python",
            "[install directory]/agent-state/main.py"
          ]
        }
      }
    }
  3. Important: Update the paths in the configuration:

    • Replace [install directory]/agent-state with the absolute path to this project on your system

    • Ensure the path uses forward slashes on all platforms

  4. Restart Claude Desktop for the changes to take effect.

Setting up MCP in Cursor (OpenCode)

  1. Open Cursor settings:

    • Press Cmd+, (macOS) or Ctrl+, (Windows/Linux) to open settings

    • Or go to File > Preferences > Settings

  2. Search for "MCP" in the settings

  3. Add the MCP server configuration in your settings JSON:

    {
      "mcp.servers": {
        "agent-state": {
          "command": "uv",
          "args": [
            "run",
            "python",
            "[install directory]/agent-state/main.py"
          ]
        }
      }
    }
  4. Important: Update the paths in the configuration:

    • Replace [install directory]/agent-state with the absolute path to this project on your system

    • Use forward slashes for paths even on Windows

  5. Restart Cursor for the changes to take effect.

Alternative: Using the virtual environment directly

If you prefer to use the virtual environment's Python directly:

  1. Find the path to your virtual environment's Python:

    which uv run python  # Shows the resolved path
  2. Use that path in your MCP configuration instead of uv run python.

Development

Code Quality

  • Run linting:

    uv run ruff check .
  • Run type checking:

    uv run pyright
  • Format code:

    uv run ruff format .

Project Structure

  • main.py - Main MCP server with agent state and log management tools

  • AGENTS.md - Coding style guidelines for this project

  • pyproject.toml - Project configuration and dependencies

License

MIT

Available Tools

4 tools
agent_state_load_logA

Load the last num_chars characters from the log file.

Args: directory: Absolute path to the GitHub worktree or repository directory where the log file is located num_chars: The number of characters to retrieve from the end of the log

Returns: The last num_chars characters from the log, or the entire log if it's shorter

Inputs: directory (required), num_chars (required). Returns: result

agent_state_load_stateB

Load the current agent state from the state file.

Args: directory: Absolute path to the GitHub worktree or repository directory where the state file is located

Returns: The current state string, or empty string if the file doesn't exist

Inputs: directory (required). Returns: result

agent_state_log_messageB

Append a message to the log file.

Args: directory: Absolute path to the GitHub worktree or repository directory where the log file should be saved message: The message to append to the log

Inputs: directory (required), message (required).

agent_state_update_stateA

Update the agent state file, replacing its contents.

Args: directory: Absolute path to the GitHub worktree or repository directory where the state file should be saved state: The current state description of what the agent is trying to do

Inputs: directory (required), state (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: load_log retrieves log data, load_state retrieves state data, log_message appends to the log, and update_state replaces state data. There is no overlap in functionality, and the resource-action pairs are unambiguous.

    Naming Consistency5/5

    All tool names follow a consistent pattern: 'agent_state_' prefix followed by a verb_noun combination (e.g., load_log, update_state). This uniformity makes the tools predictable and easy to understand as a set.

    Tool Count5/5

    With 4 tools, this server is well-scoped for managing agent state and logs. Each tool serves a specific, necessary function (read/write for both state and log files), and there are no redundant or missing operations for this domain.

    Completeness5/5

    The tool set provides complete CRUD-like coverage for the domain: it supports reading and writing both state and log files. There are no gaps in functionality for managing agent persistence, and agents can perform all expected operations without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent activity journal for AI agents - enables logging and querying decisions, changes, errors, and observations across sessions.
      3 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides an external, validated state database for LLM agents to manage long-horizon tasks, with tools for defining schemas, invariants, actions, procedures, and branching, preventing state drift and compounding errors.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides durable mission state for AI agents, enabling crash-safe recovery, verified completion, and explicit reconciliation of uncertain side effects without duplicate or blind retries.
      4
      Apache 2.0