claim
Acquire or refresh exclusive access to an MCP instance to prevent conflicts. Returns denied if held by another owner; optionally force-steal for urgent cases.
Instructions
Acquire (or refresh) a lock on an MCP instance. Returns ok:true with action=claimed (fresh) or refreshed (same owner re-claiming). If another owner holds the lock, returns ok:false with error=denied and details about the current owner — pick a different instance or pass force=true to steal (use sparingly; the current holder will get unexpected behavior). Owner is auto-detected from the calling session (OpenCode run ID, Claude Code session ID, or shell PPID); pass explicit owner to override. Default TTL is 30 minutes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ttl | No | How long to hold the claim. Format: <number><unit> where unit is s/m/h, e.g. '30m', '2h', '45s'. Raw integers are interpreted as seconds. Defaults to 30m. | |
| note | No | Free-form note attached to the claim, visible in list/who output. Useful for explaining why a long claim is held (e.g. 'PR #123 side-by-side comparison'). | |
| force | No | Steal the lock from its current owner. The displaced owner is not notified and will get DENIED on its next operation. Use only with good reason. | |
| owner | No | Explicit owner identifier. Omit to let mcp-locks auto-detect from the calling session's env vars. Pass to coordinate with a non-MCP caller or to take ownership on behalf of a different session. | |
| instance | Yes | Instance name to claim (e.g. 'playwright2'). |