MCP server & tools

The local tool surface your agent uses to operate Qalatra.

Qalatra runs a Model Context Protocol server at http://localhost:3457/mcp. Any MCP-aware local agent can connect and work with tasks, notes, habits, agent jobs, heartbeats, and capability discovery.

Transport

Streamable HTTP. Standard MCP. See the MCP spec for protocol details.

Claude Code config

{
  "mcpServers": {
    "qalatra": {
      "type": "http",
      "url": "http://localhost:3457/mcp"
    }
  }
}

Tool catalog

Tasks and triage

Tool	What it does
`get_todays_tasks`	Today view with active, overdue, due, events, reminders, and habits
`get_overdue_tasks`	Overdue active tasks
`get_task`	Single task by id. Omits the description, AI context and notes unless asked; pass `fields` to name columns or `"*"` for everything
`create_task`	New task; all fields optional except title
`update_task`	Patch any field
`complete_task`	Mark done
`snooze_task`	Defer until a later date
`search_tasks`	Full-text. Returns compact fields by default; `fields` selects columns
`rename_project`	Rename across all tasks

Daily notes

`get_daily_note`	Get a note by date
`update_daily_note`	Replace a date's markdown content
`get_week_notes`	Get the seven daily notes ending on a date

Habits

`list_habits`	Habit list with recent status
`log_habit`	Mark a habit done or skipped
`create_habit`	Create a new habit
`get_habit_history`	Read a habit's log history. Pass `start`/`end` and `summary` (week or month) to audit a long range without pulling every day

Agents and heartbeats

`queue_agent_job`	Queue a task for its assigned agent
`list_agent_jobs`	List recent jobs, optionally by task or status; ten per page by default
`get_agent_job`	Read one job's status and the tail of its result; `result_chars` sizes the tail, `0` returns it whole
`list_heartbeats`	Scheduled background agents, with their schedule and next run times
`create_heartbeat`	Create a recurring background agent run, on an interval or a cron schedule (`cron_expression` plus an IANA `timezone`, e.g. `0 5 * * 2-5` for 05:00 Tuesday to Friday)
`update_heartbeat`	Edit a heartbeat's prompt or schedule (pass `cron_expression: null` to switch a cron heartbeat back to an interval), or set `active` to pause/resume idempotently (safe to repeat, unlike `toggle_heartbeat`)

Capabilities

`list_capabilities`	List structured capabilities derived from agent folders
`search_capabilities`	Find relevant agents, skills, workflows, or knowledge by intent
`get_capability`	Inspect files, permissions, and delegation metadata
`rescan_capabilities`	Refresh the registry from disk

Rate limits

None. It's your machine.

Security

MCP binds to 127.0.0.1 by default. The MCP server validates the same bearer tokens as the Qalatra API, controlled by the QALATRA_MCP_AUTH environment variable:

Mode	Behavior
`local-bypass` (default)	Loopback requests skip auth. Non-loopback require a valid token. Safe for desktop and same-box Claude Code.
`required`	Every request needs a valid token. Use this on any box with an MCP tunnel hostname.
`off`	No auth. Explicit opt-out — only use on fully private networks.

⚠️ Tunnel warning: behind a Cloudflare tunnel, traffic arrives from 127.0.0.1 (the local cloudflared daemon) and looks like loopback. local-bypass is not safe on a tunneled box. Any box with an MCP ingress hostname must set QALATRA_MCP_AUTH=required in its systemd service.

To reach MCP from another machine, expose port 3457 through a separate tunnel hostname and connect with mcp-remote:

npx -y mcp-remote https://mcp-<box>.qalatra.com/mcp \
  --header "Authorization: Bearer <token>"

The same tokens created in Settings → Instances → Access Tokens work for both the API and MCP. See Remote instances for full tunnel setup.