Skip to main content
Glama
tianhuil

Agent State MCP Server

by tianhuil
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryYes
num_charsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the tail-reading behavior and the edge case (returning entire log if shorter), but omits safety characteristics, error handling (file not found), and side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Uses a structured docstring format with Args and Returns sections. The opening sentence summarizes the operation, and every subsequent line provides specific parameter or return value details without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (2 primitive parameters) and existence of an output schema, the description is nearly complete. It documents both parameters and return behavior, though it could be improved by mentioning error conditions like missing files.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description fully compensates via the Args block. It clarifies that 'directory' expects an absolute path to a GitHub worktree and that 'num_chars' retrieves from the end of the log, adding crucial context absent from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the exact operation (Load), resource (log file), and scope (last num_chars characters). It clearly distinguishes from sibling tools like 'load_state' by explicitly referencing the 'log file' rather than state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus siblings (e.g., when to load logs vs. loading state) nor does it mention prerequisites like the log file's existence. Only behavioral edge cases are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. Discloses critical 'empty string if file doesn't exist' behavior, but fails to explicitly state read-only nature, thread-safety, or state file format expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Uses structured Args/Returns format that is concise and front-loaded with purpose. Information density is high with no redundant sentences, though pseudo-code style is slightly less natural than prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Appropriately complete for a single-parameter read operation. Leverages existence of output schema to avoid over-explaining return values while still disclosing the empty-string edge case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Excellent compensation for 0% schema coverage. Describes 'directory' as 'Absolute path to the GitHub worktree or repository directory where the state file is located', providing domain context (GitHub) and file location semantics beyond raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States specific verb (Load) + resource (agent state) + source (state file). Distinguishes from siblings implicitly via 'load' vs 'update' (update_state) and 'state' vs 'log' (load_log), though explicit differentiation is absent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no guidance on when to use this versus agent_state_update_state (read vs write) or agent_state_load_log (state vs log history). No prerequisites or conditions specified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryYes
messageYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure but fails to address critical traits: it does not specify the log file naming convention, concurrency behavior, encoding, maximum size limits, or whether the operation is atomic. It only confirms the append operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately concise with a clear first sentence stating the action. The Args structure efficiently documents parameters without redundancy, though the mixture of narrative and docstring-style formatting is slightly inconsistent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately covers the two input parameters but leaves gaps regarding return values (no output schema exists), error conditions, and the specific log file path/name generation. For a simple logging utility, this is minimally viable but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Given 0% schema description coverage, the Args section effectively compensates by providing clear semantics for both parameters. It specifies that 'directory' requires an absolute path to a GitHub worktree/repository and that 'message' is the content to append, though it omits format constraints or validation rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the core action ('Append a message to the log file') with a specific verb and resource. However, it does not explicitly differentiate from the sibling tool 'agent_state_load_log' or clarify when logging is preferred over state updates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the sibling state management tools (load_log, load_state, update_state). There is no mention of prerequisites, such as whether the directory must exist or if the log file is created automatically.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryYes
stateYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It successfully discloses the destructive replacement behavior, but omits other critical behavioral traits such as whether it creates the file/directory if missing, atomicity guarantees, or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a one-sentence purpose statement followed by a clear Args block. There is minimal redundancy, though the Args formatting consumes space that could be in the schema itself.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, output schema, and schema descriptions, the description provides adequate but incomplete coverage. It misses error handling behavior, return values (success/failure indicators), and file format details that would be necessary for robust agent operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the Args block fully compensates by providing detailed semantics: 'directory' is clarified as an absolute path to a GitHub worktree/repository, and 'state' is explained as the current state description of the agent's task. This adds complete meaning beyond the raw schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool updates the agent state file and explicitly notes the destructive 'replacing its contents' behavior. This distinguishes it from sibling load_state (read) and log_message (likely append) operations, though it doesn't explicitly name those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the sibling load_state or log_message tools, nor any mention of prerequisites (e.g., directory must exist) or idempotency considerations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv0.1.0
    • First observedagent_state_load_log
    • First observedagent_state_load_state
    • First observedagent_state_log_message
    • First observedagent_state_update_state
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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 issues

Resources

Related MCP Connectors

Related MCP Servers

  • joa

    neethanwu
    A
    license
    Not graded
    quality
    C
    maintenance
    Persistent activity journal for AI agents - enables logging and querying decisions, changes, errors, and observations across sessions.
    7 npm
    1
    MIT

  • worldmodel-mcp

    CocoaBeans
    F
    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.
    -

  • AgentAudit MCP

    Rumblingb
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides an immutable, tamper-evident audit trail for AI agents, enabling event logging with cryptographic chaining, search, verification, and statistics.
    2
    MIT