Agent State MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Agent State MCP Server log that the initial data collection phase is complete"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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+
uvpackage manager
Installation
Install dependencies:
uv syncActivate 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.pySetting up MCP in Claude Desktop
Open Claude Desktop settings:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the MCP server configuration:
{ "mcpServers": { "agent-state": { "command": "uv", "args": [ "run", "python", "[install directory]/agent-state/main.py" ] } } }Important: Update the paths in the configuration:
Replace
[install directory]/agent-statewith the absolute path to this project on your systemEnsure the path uses forward slashes on all platforms
Restart Claude Desktop for the changes to take effect.
Setting up MCP in Cursor (OpenCode)
Open Cursor settings:
Press
Cmd+,(macOS) orCtrl+,(Windows/Linux) to open settingsOr go to
File > Preferences > Settings
Search for "MCP" in the settings
Add the MCP server configuration in your settings JSON:
{ "mcp.servers": { "agent-state": { "command": "uv", "args": [ "run", "python", "[install directory]/agent-state/main.py" ] } } }Important: Update the paths in the configuration:
Replace
[install directory]/agent-statewith the absolute path to this project on your systemUse forward slashes for paths even on Windows
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:
Find the path to your virtual environment's Python:
which uv run python # Shows the resolved pathUse 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 pyrightFormat code:
uv run ruff format .
Project Structure
main.py- Main MCP server with agent state and log management toolsAGENTS.md- Coding style guidelines for this projectpyproject.toml- Project configuration and dependencies
License
MIT
Available Tools
4 toolsagent_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Durable background job execution, async task scheduling, and state persistence for AI agents.
Persistent work tracking for AI agents: tasks, status and history that follow you across machines
A home for your agents: an owned book of record any AI agent can write to, with provenance and undo.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenancePersistent, append-only event log for AI agent coordination, enabling agents to publish, query, and react to structured events across tools and sessions.1-
- AlicenseNot gradedqualityDmaintenancePersistent activity journal for AI agents - enables logging and querying decisions, changes, errors, and observations across sessions.3 npm1MIT
- AlicenseNot gradedqualityCmaintenanceProvides 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
- AlicenseNot gradedqualityBmaintenanceProvides durable mission state for AI agents, enabling crash-safe recovery, verified completion, and explicit reconciliation of uncertain side effects without duplicate or blind retries.4Apache 2.0