Agent Claim MCP

Languages: English · 日本語 · 简体中文 · Русский · Español

Use Agent Claim MCP when multiple coding agents share one worktree and you need a tiny local coordination primitive before edits, not a full orchestration framework. It gives agents one job: claim paths, detect collisions, and release ownership so parallel work stops stomping the same files.

Agent Claim MCP is a local-first MCP server for Claude Code, Cursor, Cline, and other MCP clients that need file ownership coordination without queues, planners, or custom AGENTS.md conventions. The current release surface centers on three bounded actions only: claim normalized paths, inspect who owns them, and release by path or claim id with explicit conflict reporting across separate sessions.

Release status: @vk0/agent-claim-mcp@1.0.0 is live on npm, so the npx -y @vk0/agent-claim-mcp install path is now the truthful default for external users. Phase 5 external proof may be satisfied by either Official MCP Registry validation or a live Smithery listing, but the current proof state remains pending until one of those public artifacts is explicitly verified. Official MCP Registry validation is still pending, so do not describe the package as registry-accepted or marketplace-listed until a real registry or Smithery proof URL is cited.

Milestone truth: the product wedge stays narrow, 3 tools plus a local JSON ledger for shared-worktree collision prevention, not a broader orchestration platform.

Current next manual step: complete the pending human rerun and verification path for Official MCP Registry proof, then record the verdict from that run instead of assuming acceptance from npm availability.

Registry rerun quickstart

Current truthful state:

• npm 1.0.0 is live
• Official MCP Registry acceptance is still pending
• workflow 25282612113 did not complete the registry validation path
• the repo is now past the earlier NPM_TOKEN secret-fix step, but the registry proof still needs a human rerun plus verification before it can be treated as accepted

Exact rerun command:

gh run rerun 25282612113 --repo vk0dev/agent-claim-mcp

After the rerun, verify in this order:

1. confirm the rerun completed successfully in GitHub Actions
2. run npm run preflight:registry
3. follow docs/official-registry-validation-runbook.md
4. only then record registry acceptance as proven

Operator shortcut: use the runbook's Quick operator path for the exact rerun-to-verification order, and treat npm-live status as separate from registry-proof status.

Why / When to use

Choose this server when your workflow already has task routing, but still needs a simple lock-like primitive at edit time:

• two or more agents can touch the same repo in parallel
• you want collision detection before file edits, not after merge conflicts
• you want claims to expire automatically with TTLs
• you want a narrow primitive that another agent can understand from name + description alone
• you do not want a bundled rules engine, queue runner, or orchestration platform

Installation

The canonical external install path is now the published npm package:

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

Status note: npm install is live today, but Official MCP Registry validation and Smithery/other marketplace proof are still not established, so treat the package as npm-available first rather than marketplace-verified.

If you are developing from a local checkout instead of the published package, you can still point your MCP client at the built dist/server.js directly.

{
  "mcpServers": {
    "agent-claim": {
      "command": "node",
      "args": ["/absolute/path/to/agent-claim-mcp/dist/server.js"]
    }
  }
}

That second example is for local development only. On Windows, point your MCP client at the built dist/server.js path on your own machine instead of copying a POSIX path literally.

Build once before using the local path:

cd /Users/vkdev/projects/agent-claim-mcp
npm ci
npm run build

Claude Code

Add the stdio server to your Claude Code MCP config:

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

Claude Desktop

Claude Desktop uses ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

After saving claude_desktop_config.json, fully restart Claude Desktop so it reloads the MCP server configuration.

Cursor

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

Cline

{
  "mcpServers": {
    "agent-claim": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-claim-mcp"]
    }
  }
}

Limitations

This server is intentionally narrow and local-first. Install it when your agents share one filesystem view, not when you need distributed coordination.

• Claims live in a local ledger on disk, so they only coordinate sessions that can read and write the same worktree.
• It is not a hosted lock service, queue, or scheduler, and it does not replicate claims across machines by itself.
• TTL expiry is protective cleanup, not a substitute for higher-level task ownership or human review.
• Path normalization reduces shape mismatches, but agents still need to point at the same repo root or cwd for claims to line up.
• If your workflow needs cross-host coordination, central audit policy, or mandatory approvals, pair this server with a separate orchestration layer instead of stretching the claim ledger beyond its scope.

For a real multi-agent run before publishing, see DOGFOOD.md and the proof artifacts in docs/dogfood-report.md.

Tools

claim_files

Create or refresh a local file-claim entry so parallel agents can see ownership before editing and avoid stomping the same worktree paths during active tasks. Conflict responses are explicit, so overlapping claims across separate sessions do not stay implicit or in-memory only.

Input

{
  "agentId": "coder-a",
  "taskId": "task-123",
  "paths": ["src/foo.ts", "src/bar.ts"],
  "ttlSeconds": 3600,
  "note": "working on parser cleanup",
  "cwd": "/repo"
}

Output

{
  "ok": true,
  "claimed": ["/repo/src/bar.ts", "/repo/src/foo.ts"],
  "conflicts": [],
  "ledgerVersion": 1,
  "claimedUntil": "2026-05-03T16:00:00.000Z"
}

If any requested path is already claimed by another active owner, the tool returns ok: false and writes nothing.

release_claim

Remove an existing claim owned by the current agent so finished, paused, or reassigned work stops blocking other agents from safely editing the same paths.

Input

{
  "agentId": "coder-a",
  "paths": ["src/foo.ts"],
  "cwd": "/repo"
}

Output

{
  "ok": true,
  "released": ["/repo/src/foo.ts"],
  "missing": [],
  "ledgerVersion": 1
}

Only the current owner can release an active claim, whether you target it by claimId or by normalized paths, so cleanup works after real multi-agent runs and path-shape variants resolve consistently.

whose_claim

Read the local ledger and explain whether a file path is free or currently claimed, including owner, task, note, and expiry metadata for safe coordination across separate sessions sharing the same worktree.

Input

{
  "paths": ["src/foo.ts", "src/bar.ts"],
  "cwd": "/repo",
  "includeExpired": false
}

Output

{
  "results": [
    {
      "path": "/repo/src/bar.ts",
      "claimed": false
    },
    {
      "path": "/repo/src/foo.ts",
      "claimed": true,
      "ownerAgentId": "coder-a",
      "taskId": "task-123",
      "note": "working on parser cleanup",
      "expiresAt": "2026-05-03T16:00:00.000Z",
      "claimId": "2a08b70c-4203-44a2-b833-31592472de1e"
    }
  ],
  "ledgerVersion": 1
}

Real samples

1. coder-A claims foo.ts

{
  "tool": "claim_files",
  "arguments": {
    "agentId": "coder-A",
    "taskId": "task-42",
    "paths": ["src/foo.ts"],
    "note": "refactoring the claim parser",
    "cwd": "/repo"
  }
}

{
  "ok": true,
  "claimed": ["/repo/src/foo.ts"],
  "conflicts": [],
  "ledgerVersion": 1,
  "claimedUntil": "2026-05-03T16:00:00.000Z"
}

2. coder-B collides on the same file

{
  "tool": "claim_files",
  "arguments": {
    "agentId": "coder-B",
    "paths": ["src/foo.ts", "src/new.ts"],
    "cwd": "/repo"
  }
}

{
  "ok": false,
  "claimed": [],
  "conflicts": [
    {
      "path": "/repo/src/foo.ts",
      "ownerAgentId": "coder-A",
      "expiresAt": "2026-05-03T16:00:00.000Z"
    }
  ],
  "ledgerVersion": 1,
  "claimedUntil": "2026-05-03T16:00:00.000Z"
}

3. coder-A releases the file

{
  "tool": "release_claim",
  "arguments": {
    "agentId": "coder-A",
    "paths": ["src/foo.ts"],
    "cwd": "/repo"
  }
}

{
  "ok": true,
  "released": ["/repo/src/foo.ts"],
  "missing": [],
  "ledgerVersion": 1
}

Troubleshooting

claim_files returns ok: false