agentdraft-mcp 0.1.0

MCP server for AgentDraft — expose the scheduling source of truth to MCP-aware AI clients (Claude Desktop, Cursor, Cline, etc.)

agentdraft-mcp — MCP server for AgentDraft

An MCP server that exposes AgentDraft — the scheduling source of truth for AI agents — as a set of tools any MCP-aware AI client can call.

Use this if your agent runtime is Claude Desktop, Claude Code, Cursor, Cline, an OpenAI Agents SDK app, or any other MCP host. The server is a thin wrapper around the agentdraft Python SDK — same auth, same errors, same semantics as the REST API and the language SDKs.

Install

pip install agentdraft-mcp

Requires Python 3.10+ and a valid avs_live_… agent key from the AgentDraft dashboard.

Configure your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows/Linux:

{
  "mcpServers": {
    "agentdraft": {
      "command": "agentdraft-mcp",
      "env": {
        "AGENTDRAFT_API_KEY": "avs_live_..."
      }
    }
  }
}

Cursor / Cline / generic stdio host

{
  "mcpServers": {
    "agentdraft": {
      "command": "python",
      "args": ["-m", "agentdraft_mcp"],
      "env": {
        "AGENTDRAFT_API_KEY": "avs_live_..."
      }
    }
  }
}

For local development against a dev backend, also set AGENTDRAFT_BASE_URL=http://localhost:8080.

Tools

Tool	Purpose
whoami	Confirm the API key and return the agent's identity, priority, scopes
get_availability	List slots open to the calling agent in [start, end)
create_hold	Reserve a slot tentatively (30 s TTL)
release_hold	Release a hold so other agents can claim it
commit_booking	Finalize a booking — atomic compare-and-swap
cancel_booking	Cancel a committed booking the calling agent owns

All times are ISO 8601 strings (2026-06-01T14:00:00Z). All write tools accept an idempotency_key for safe retries.

How conflicts surface

When two agents race for the same slot, exactly one wins. Losing agents receive a structured outranked payload — not a string error:

{
  "error": "outranked",
  "winning_booking_id": "bkg_…",
  "winning_agent_id": "agt_…",
  "winning_agent_priority": 1,
  "your_priority": 3,
  "message": "Your booking was outranked. Read winning_agent_id and propose an alternate slot rather than retrying."
}

Your agent should branch on this and propose an alternate, not retry the same slot.

How this differs from the AgentDraft SDKs

	Python/TS SDK	MCP server
Caller	App code you wrote	An AI client (Claude Desktop, etc.)
Transport	HTTPS direct to api.agentdraft.io	stdio between the MCP host and this process
Auth	Client(api_key=…)	AGENTDRAFT_API_KEY env var
Semantics	Same	Same
Errors	Typed Python exceptions	Structured JSON in the tool result

Use the SDK when you are writing the agent. Use this MCP server when someone else's agent runtime (Claude Desktop, Cursor, Cline, generic MCP host) needs to call AgentDraft on a user's behalf without custom code.

Links

• Protocol spec: https://agentdraft.io/spec
• API docs: https://agentdraft.io/docs
• Python SDK: agentdraft
• TypeScript SDK: @agentdraft/sdk
• Source: https://github.com/GipsyChef/agentdraft
• Issues: https://github.com/GipsyChef/agentdraft/issues

Security

Found a vulnerability? See SECURITY.md. Do not open a public issue for a security report.

Contributing

See CONTRIBUTING.md. This package lives inside the GipsyChef/agentdraft monorepo under sdks/mcp/.

License

MIT — see LICENSE.