Agenthold

What edobusy/agenthold MCP server does

The edobusy/agenthold MCP server provides coordination primitives for agents that may work on the same resource at the same time. It is intended to prevent one agent from overwriting another agent's work without detecting the conflict. The server uses SQLite as its backing store and maintains versioned state, claims, and an append-only audit log.

Resources can represent workspace files or opaque custom names. File resources use canonical URIs such as file://default/path/to/file, while custom resources use custom://name. Bare paths are also accepted and resolved against a configured workspace. Equivalent path forms are normalized so agents do not accidentally coordinate on separate keys for the same resource.

How it works

The edobusy/agenthold MCP server combines exclusive claims with optimistic concurrency control. An agent first registers to receive an identifier, then claims a resource before changing it. If another agent already holds the claim, the response reports that the resource is busy. The waiting agent can choose another resource or use the wait tool until the claim is released or a timeout occurs.

Each stored value has a version. A write based on an older version is rejected and includes the current value, allowing the agent to reread state, recalculate, and retry. This approach avoids keeping a database lock open while an agent performs network requests or generates text.

When releasing a resource, the agent supplies an outcome describing what happened. That outcome remains available to a later claimant, helping the next agent understand prior work instead of relying on stale assumptions. Claim responses can also include information about previous deletion, movement, abandonment, or expiration activity when relevant.

Setup and configuration

Install the Python package with pip install agenthold or uv pip install agenthold. An MCP client can launch the server with the agenthold command. The example configuration passes --db with a path for the SQLite database.

Without workspace flags, the process creates a default workspace based on its current working directory. Additional workspaces can be supplied with repeatable --workspace name=path options, allowing one process to coordinate resources across separate codebases. The database location and workspace paths should be selected consistently for all clients that need to share state.

Tools and capabilities

The server exposes five MCP tools:

• agenthold_register creates an agent identity. Registration is required before claiming or releasing resources.
• agenthold_claim requests exclusive access to a resource and returns its version when successful.
• agenthold_release ends a claim and records an explicit outcome.
• agenthold_status reports whether a resource is available or claimed and does not require registration.
• agenthold_wait blocks until a claimed resource becomes available or its timeout expires.

Limitations and notes

The edobusy/agenthold MCP server is coordination infrastructure, not an agent orchestration framework. It supplies shared state and resource ownership while the surrounding framework remains responsible for the actual work and retry behavior.

Agents must register before using claim or release. A claim controls access to the named resource, but the agent still needs to perform the underlying file or state modification through its other tools. For optimistic concurrency control to help, agents must use the returned version and respond to conflicts by rereading and retrying.

Path traversal and dot segments are rejected. On case-insensitive platforms, file paths are matched without case distinctions; custom resource names remain case-sensitive.