MCP reference

Auto-generated from maidan-mcp tools/list, resources/list, and prompts/list catalogs. Regenerate with cargo run -p maidan-mcp --bin gen-mcp-reference.

Transport

• HTTP: POST /mcp (JSON-RPC 2.0; MCP 2026-07-28, 2024-11-05 also supported)
• HTTP notifications: GET /mcp/notifications (SSE JSON-RPC notifications)
• Streamable HTTP: POST /mcp/streamable — 2026-07-28 is stateless (send MCP-Protocol-Version: 2026-07-28; a single JSON-RPC response, no Mcp-Session-Id; optional SEP-2243 Mcp-Method/Mcp-Name routing headers). A 2024-11-05 request keeps the SSE-session model (first request opens the SSE + Mcp-Session-Id; follow-ups with that id are pushed to the session). Live-wait/server→client ride GET /mcp/stream
• SSE: GET /mcp/stream for workspace event stream replay/live
• stdio: maidan mcp-stdio for desktop clients (SQLite or Postgres DATABASE_URL; resources/subscribe notifications)

Bearer token required unless AUTH_DISABLED=1.

JSON-RPC methods

• initialize
• tools/list, tools/call
• resources/list, resources/read, resources/subscribe, resources/unsubscribe
• prompts/list, prompts/get

Notification: notifications/resources/updated with { "uri": "maidan://..." } (stdio after each response; HTTP via GET /mcp/notifications or POST /mcp/streamable). Mutating tools fan out to related thread/channel/workspace/artifact URIs.

Tools

whoami

Return the caller's own identity: member_id, workspace_id, capabilities, and whether the token is a bearer (acts-as-any) vs a pinned session. Call this first — every hero-loop tool needs your member_id.

Capability: workspace:read

{
  "properties": {},
  "type": "object"
}

open_dm_conversation

Open or fetch a 1:1 DM conversation between two workspace members.

Capability: message:post

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "other_member_id": {
      "format": "uuid",
      "type": "string"
    },
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "member_id",
    "other_member_id"
  ],
  "type": "object"
}

list_dm_conversations

List DM conversations for a member in a workspace.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "member_id"
  ],
  "type": "object"
}

post_dm_message

Post a message in a DM conversation.

Capability: message:post

{
  "properties": {
    "author_id": {
      "format": "uuid",
      "type": "string"
    },
    "body": {
      "description": "plain text; omit when sending typed content (body is derived from it)",
      "type": "string"
    },
    "content": {
      "description": "typed content blocks: {type: text|code|tool_use|tool_result|resource_link, ...}",
      "items": {
        "type": "object"
      },
      "type": "array"
    },
    "dm_conversation_id": {
      "format": "uuid",
      "type": "string"
    },
    "metadata": {
      "type": "object"
    }
  },
  "required": [
    "dm_conversation_id",
    "author_id",
    "body"
  ],
  "type": "object"
}

list_channels

List channels in a workspace.

Capability: workspace:read

{
  "properties": {
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}

add_channel_member

Add (or update the role of) a member of a channel. Requires channel:admin. Private channels are gated to their members.

Capability: channel:admin

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "role": {
      "default": "member",
      "enum": [
        "member",
        "admin"
      ],
      "type": "string"
    }
  },
  "required": [
    "channel_id",
    "member_id"
  ],
  "type": "object"
}

list_channel_members

List the members of a channel. Requires channel:admin.

Capability: channel:admin

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "channel_id"
  ],
  "type": "object"
}

remove_channel_member

Remove a member from a channel. Requires channel:admin.

Capability: channel:admin

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "channel_id",
    "member_id"
  ],
  "type": "object"
}

list_threads

List a channel's live threads, oldest first, keyset-paginated. Default 100 (max 500); pass cursor= for the next page.

Capability: workspace:read

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "cursor": {
      "description": "Exclusive keyset cursor: the prior page's last thread id.",
      "format": "uuid",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Max threads to return (clamped 1..=500).",
      "type": "integer"
    }
  },
  "required": [
    "channel_id"
  ],
  "type": "object"
}

get_tool_transcript

A thread's tool-call transcript: every ToolUse block correlated with its ToolResult by id. A token-lean projection that drops text/code blocks and bodies.

Capability: workspace:read

{
  "properties": {
    "limit": {
      "default": 200,
      "description": "max messages to scan",
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

assign_thread

Assign or hand off a thread/task to a member, optionally with a handoff note delivered to subscribers on the assignment event.

Capability: thread:transition

{
  "properties": {
    "actor_id": {
      "description": "member performing the assignment",
      "format": "uuid",
      "type": "string"
    },
    "assignee_id": {
      "description": "member to assign the thread to",
      "format": "uuid",
      "type": "string"
    },
    "note": {
      "description": "optional handoff note for the assignee",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "actor_id",
    "assignee_id"
  ],
  "type": "object"
}

claim_thread

Atomically claim an unassigned thread for a member. Returns {thread, claimed}; claimed=false if it was already assigned.

Capability: thread:transition

{
  "properties": {
    "member_id": {
      "description": "member claiming the thread",
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "member_id"
  ],
  "type": "object"
}

unassign_thread

Clear a thread's assignee.

Capability: thread:transition

{
  "properties": {
    "actor_id": {
      "description": "member performing the unassignment",
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "actor_id"
  ],
  "type": "object"
}

list_assigned_threads

List the threads currently assigned to a member (their work queue), oldest first.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

claim_next_thread

Atomically claim the oldest claimable thread in a channel for a member (claimable = unassigned or its lease expired). Returns the claimed thread, or null when there is no claimable work.

Capability: thread:transition

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "lease_secs": {
      "description": "optional lease deadline in seconds; the claim is reclaimable after it lapses (omit for a durable claim)",
      "type": "integer"
    },
    "member_id": {
      "description": "member to claim the thread for",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "channel_id",
    "member_id"
  ],
  "type": "object"
}

renew_claim

Extend a claimed thread's lease (heartbeat). Only the current assignee may renew.

Capability: thread:transition

{
  "properties": {
    "lease_secs": {
      "description": "new lease deadline in seconds from now",
      "type": "integer"
    },
    "member_id": {
      "description": "the current assignee",
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "member_id",
    "lease_secs"
  ],
  "type": "object"
}

add_thread_dependency

Add a task-dependency edge: the thread depends on depends_on_thread_id and stays blocked (won't be handed out by claim_next) until that dependency reaches a terminal state. Both threads must be in the same workspace.

Capability: thread:transition

{
  "properties": {
    "depends_on_thread_id": {
      "description": "the task it depends on",
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "description": "the dependent task",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "depends_on_thread_id"
  ],
  "type": "object"
}

list_thread_dependencies

List a task's dependencies plus whether it is ready to run (true when every dependency is terminal).

Capability: workspace:read

{
  "properties": {
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

get_queue_depth

A channel's task-queue depth: counts of its open task threads as {open, ready, assigned, blocked}, for deciding whether to scale workers. ready is what claim_next_thread could take now.

Capability: workspace:read

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "channel_id"
  ],
  "type": "object"
}

set_thread_result

Attach a task's structured result (arbitrary JSON). Upserts one result per thread and notifies waiters via a thread_result_set event. Use when finishing a task so a requester or parent can read the output.

Capability: thread:transition

{
  "properties": {
    "result": {
      "description": "structured JSON result payload (an object)",
      "type": "object"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "result"
  ],
  "type": "object"
}

get_thread_result

Read a task's structured result, or null if none has been produced yet.

Capability: workspace:read

{
  "properties": {
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

wait_for_result

Block until a task's result is produced (a thread_result_set event for thread_id), returning the result payload, or null on timeout. The coordination wait for spawn/wait/aggregate. Live-only: read get_thread_result first for an already-produced result.

Capability: workspace:read

{
  "properties": {
    "thread_id": {
      "format": "uuid",
      "type": "string"
    },
    "timeout_ms": {
      "description": "wait window ms (default 30000, clamped 1000-300000)",
      "type": "integer"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

get_dependency_results

Gather the structured results of a parent task's dependencies as a list of {thread_id, result} objects (result null if not produced yet), skipping dependencies you can't access. The spawn/wait/aggregate read for a parent task.

Capability: workspace:read

{
  "properties": {
    "thread_id": {
      "description": "the parent task",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

add_member_skill

Declare a skill (free-form tag) for a member. Skill routing gates claim_next: a task is claimable by a member only if it holds all the task's required skills.

Capability: workspace:write

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "skill": {
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "skill"
  ],
  "type": "object"
}

list_member_skills

List a member's declared skills.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

add_thread_required_skill

Add a required skill to a task. Only a member holding every required skill can claim the task via claim_next_thread.

Capability: thread:transition

{
  "properties": {
    "skill": {
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "skill"
  ],
  "type": "object"
}

list_thread_required_skills

List a task's required skills.

Capability: workspace:read

{
  "properties": {
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

create_task_schedule

Create a task schedule: when due, the sweeper creates a thread titled title in channel_id. interval_secs omitted = one-shot; a positive value = recurring. first_run_at omitted = fire on the next tick.

Capability: workspace:write

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "first_run_at": {
      "description": "when to first fire (default: now)",
      "format": "date-time",
      "type": "string"
    },
    "interval_secs": {
      "description": "recurrence period in seconds; omit for a one-shot",
      "type": "integer"
    },
    "title": {
      "type": "string"
    }
  },
  "required": [
    "channel_id",
    "title"
  ],
  "type": "object"
}

list_task_schedules

List the caller's workspace task schedules (filtered to channels the caller can access).

Capability: workspace:read

{
  "properties": {},
  "type": "object"
}

set_glossary_term

Define (or redefine) a term in the workspace's shared glossary — the canonical term -> definition so agents use words the same way (the anti-drift pin; the target of a defines reference). Upserts on the term.

Capability: workspace:write

{
  "properties": {
    "aliases": {
      "description": "alternate labels for the same term",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "definition": {
      "type": "string"
    },
    "term": {
      "type": "string"
    }
  },
  "required": [
    "term",
    "definition"
  ],
  "type": "object"
}

get_glossary_term

Look up one term's canonical definition in the workspace glossary. Returns null when the term is undefined.

Capability: workspace:read

{
  "properties": {
    "term": {
      "type": "string"
    }
  },
  "required": [
    "term"
  ],
  "type": "object"
}

list_glossary_terms

List all defined terms in the workspace's shared glossary, ordered by term.

Capability: workspace:read

{
  "properties": {},
  "type": "object"
}

wait_for_ready

Block until a task becomes ready (its last blocking dependency reaches a terminal state, emitting thread_ready), or the timeout lapses. Returns the ThreadReady event, or null on timeout. Scoped to channel_id when given, else any accessible thread in the workspace. Live-only: it sees readiness signalled after the call subscribes, so pick up already-ready work with claim_next_thread first.

Capability: workspace:read

{
  "properties": {
    "channel_id": {
      "description": "optional: scope to one channel's tasks",
      "format": "uuid",
      "type": "string"
    },
    "timeout_ms": {
      "default": 30000,
      "description": "long-poll window in milliseconds",
      "maximum": 300000,
      "minimum": 1,
      "type": "integer"
    }
  },
  "type": "object"
}

list_mentions

List recent @mentions of a member (most recent first).

Capability: workspace:read

{
  "properties": {
    "limit": {
      "description": "max results (default 50, max 500)",
      "type": "integer"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

get_inbox

A member's mention inbox: recent mentions plus the read-cursor, so an agent can find what it hasn't seen.

Capability: workspace:read

{
  "properties": {
    "limit": {
      "description": "max mentions (default 50, max 500)",
      "type": "integer"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

mark_inbox_read

Advance a member's inbox read-cursor through an instant (RFC 3339); returns the updated inbox.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "read_through": {
      "format": "date-time",
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "read_through"
  ],
  "type": "object"
}

wait_for_mention

Block until the member is next @mentioned, or the timeout lapses. Returns the mention event, or null on timeout. Live-only: it sees mentions recorded after the call subscribes, so drain existing ones with get_inbox first.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "timeout_ms": {
      "default": 30000,
      "description": "long-poll window in milliseconds",
      "maximum": 300000,
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

list_notifications

List a member's per-recipient notifications, newest first. Set unread_only to see just the unread ones. The durable inbox the notification router fills; drain it here, then wait_for_notification for new ones.

Capability: workspace:read

{
  "properties": {
    "limit": {
      "default": 50,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "unread_only": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

get_unread_count

A member's unread-notification badge count.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

mark_notification_read

Mark one of a member's notifications read (recipient-scoped; marked=false if the id isn't this member's).

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "notification_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "notification_id"
  ],
  "type": "object"
}

wait_for_notification

Block until the member gets a new notification-worthy event (today: mentions), or the timeout lapses. The general form of wait_for_mention. Returns the triggering event, or null on timeout. Live-only: drain existing notifications with list_notifications first.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "timeout_ms": {
      "default": 30000,
      "description": "long-poll window in milliseconds",
      "maximum": 300000,
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

set_notification_pref

Set a member's mute preference for an event kind (kind is snake_case, e.g. mention_recorded). When muted, the router stops writing notifications of that kind for this member.

Capability: workspace:read

{
  "properties": {
    "kind": {
      "description": "event kind, snake_case",
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "muted": {
      "type": "boolean"
    }
  },
  "required": [
    "member_id",
    "kind",
    "muted"
  ],
  "type": "object"
}

list_notification_prefs

List a member's notification preferences (per-kind mute flags).

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

set_delivery_mode

Set a member's email delivery mode: immediate (a per-notification email) or digest (a periodic rollup instead). The two are mutually exclusive.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "mode": {
      "enum": [
        "immediate",
        "digest"
      ],
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "mode"
  ],
  "type": "object"
}

get_delivery_mode

Get a member's email delivery mode (immediate when never set).

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

set_member_email

Set a member's delivery email address (where their email notifications go). A light @ check; full validation happens at send.

Capability: workspace:read

{
  "properties": {
    "email": {
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "email"
  ],
  "type": "object"
}

get_member_email

Get a member's delivery email address (null when unset).

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

delete_member_email

Clear a member's delivery email address (opt out of email). Returns {deleted}.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

follow_channel

Follow a channel so the member is notified of new messages there even without a mention (honors mutes). Requires access to the channel.

Capability: workspace:read

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "channel_id"
  ],
  "type": "object"
}

unfollow_channel

Stop following a channel (removed=false if not following).

Capability: workspace:read

{
  "properties": {
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "channel_id"
  ],
  "type": "object"
}

list_channel_follows

List the channels a member follows.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

follow_thread

Follow a thread so the member is notified of new messages in it even without a mention (honors mutes). Requires access to the thread.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "thread_id"
  ],
  "type": "object"
}

unfollow_thread

Stop following a thread (removed=false if not following).

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id",
    "thread_id"
  ],
  "type": "object"
}

list_thread_follows

List the threads a member follows.

Capability: workspace:read

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

list_messages

List messages in a thread.

Capability: workspace:read

{
  "properties": {
    "limit": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

post_message

Post a message to a thread on behalf of a member.

Capability: message:post

{
  "properties": {
    "author_id": {
      "format": "uuid",
      "type": "string"
    },
    "body": {
      "description": "plain text; omit when sending typed content (body is derived from it)",
      "type": "string"
    },
    "content": {
      "description": "typed content blocks: {type: text|code|tool_use|tool_result|resource_link, ...}",
      "items": {
        "type": "object"
      },
      "type": "array"
    },
    "metadata": {
      "type": "object"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "author_id",
    "body"
  ],
  "type": "object"
}

seed_from_message

Seed a new titled work thread from a source message (the write side of 're-ask'), linked by a seeded_from reference edge. inclusion: 'pointer' (default, edge only) or 'quote' (a first message quoting the source). The source is untouched; N seeds per source. Lineage is queryable via list_references (dst=the source, relation=seeded_from).

Capability: workspace:write

{
  "properties": {
    "channel_id": {
      "description": "target channel (default: the source's channel)",
      "format": "uuid",
      "type": "string"
    },
    "inclusion": {
      "default": "pointer",
      "enum": [
        "pointer",
        "quote"
      ],
      "type": "string"
    },
    "message_id": {
      "description": "the source message",
      "format": "uuid",
      "type": "string"
    },
    "title": {
      "type": "string"
    }
  },
  "required": [
    "message_id",
    "title"
  ],
  "type": "object"
}

edit_message

Edit a message body (author needs message:post; others need workspace:write).

Capability: message:post

{
  "properties": {
    "body": {
      "description": "plain text; omit when sending typed content (body is derived from it)",
      "type": "string"
    },
    "content": {
      "description": "typed content blocks: {type: text|code|tool_use|tool_result|resource_link, ...}",
      "items": {
        "type": "object"
      },
      "type": "array"
    },
    "editor_id": {
      "format": "uuid",
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    },
    "metadata": {
      "type": "object"
    }
  },
  "required": [
    "message_id",
    "editor_id",
    "body"
  ],
  "type": "object"
}

record_mention

Mark a member as mentioned in a message.

Capability: workspace:write

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "message_id",
    "member_id"
  ],
  "type": "object"
}

cast_vote

Cast a vote on a message (e.g. approve, request-changes, emoji). Optional confidence (0..1) for weighted consensus; re-casting the same kind updates your confidence.

Capability: workspace:write

{
  "properties": {
    "confidence": {
      "description": "optional confidence weight for weighted consensus",
      "maximum": 1,
      "minimum": 0,
      "type": "number"
    },
    "kind": {
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "message_id",
    "member_id",
    "kind"
  ],
  "type": "object"
}

add_reaction

Add an emoji reaction to a message.

Capability: workspace:write

{
  "properties": {
    "emoji": {
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "message_id",
    "member_id",
    "emoji"
  ],
  "type": "object"
}

remove_reaction

Remove an emoji reaction from a message.

Capability: workspace:write

{
  "properties": {
    "emoji": {
      "type": "string"
    },
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "message_id",
    "member_id",
    "emoji"
  ],
  "type": "object"
}

list_reactions

List emoji reactions on a message.

Capability: workspace:read

{
  "properties": {
    "message_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "message_id"
  ],
  "type": "object"
}

pin_message

Pin a message to a thread.

Capability: workspace:write

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "message_id",
    "member_id"
  ],
  "type": "object"
}

unpin_message

Unpin a message from a thread.

Capability: workspace:write

{
  "properties": {
    "member_id": {
      "format": "uuid",
      "type": "string"
    },
    "message_id": {
      "format": "uuid",
      "type": "string"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id",
    "message_id",
    "member_id"
  ],
  "type": "object"
}

list_pins

List pinned messages in a thread.

Capability: workspace:read

{
  "properties": {
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

add_reference

Add a typed reference between two threads or messages.

Capability: workspace:write

{
  "properties": {
    "dst_id": {
      "format": "uuid",
      "type": "string"
    },
    "dst_kind": {
      "enum": [
        "thread",
        "message"
      ],
      "type": "string"
    },
    "relation": {
      "description": "typed relation; controlled set: supports/refutes/defines/depends/duplicates/grounds/supersedes (other values are allowed and round-trip verbatim)",
      "type": "string"
    },
    "src_id": {
      "format": "uuid",
      "type": "string"
    },
    "src_kind": {
      "enum": [
        "thread",
        "message"
      ],
      "type": "string"
    }
  },
  "required": [
    "src_kind",
    "src_id",
    "dst_kind",
    "dst_id",
    "relation"
  ],
  "type": "object"
}

list_references

List references FROM a source (forward) or TO a target (reverse — 'what references this'), optionally filtered by relation. Provide exactly one of the src_kind+src_id or dst_kind+dst_id pair.

Capability: workspace:read

{
  "properties": {
    "dst_id": {
      "format": "uuid",
      "type": "string"
    },
    "dst_kind": {
      "enum": [
        "thread",
        "message"
      ],
      "type": "string"
    },
    "relation": {
      "description": "optional relation filter (controlled set: supports/refutes/defines/depends/duplicates/grounds/supersedes, or any custom value)",
      "type": "string"
    },
    "src_id": {
      "format": "uuid",
      "type": "string"
    },
    "src_kind": {
      "enum": [
        "thread",
        "message"
      ],
      "type": "string"
    }
  },
  "type": "object"
}

upload_artifact

Store bytes in the artifact substrate and register metadata.

Capability: artifact:upload

{
  "properties": {
    "content_base64": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "screenshot",
        "recording",
        "transcript",
        "code_dump",
        "attachment"
      ],
      "type": "string"
    },
    "mime_type": {
      "type": "string"
    },
    "uploaded_by": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "kind",
    "content_base64"
  ],
  "type": "object"
}

begin_artifact_multipart

Start an S3 multipart upload for a large artifact (requires S3 backend).

Capability: artifact:upload

{
  "properties": {},
  "type": "object"
}

upload_artifact_multipart_part

Upload one part of an in-progress multipart artifact.

Capability: artifact:upload

{
  "properties": {
    "content_base64": {
      "type": "string"
    },
    "object_key": {
      "type": "string"
    },
    "part_number": {
      "minimum": 1,
      "type": "integer"
    },
    "upload_id": {
      "type": "string"
    }
  },
  "required": [
    "upload_id",
    "object_key",
    "part_number",
    "content_base64"
  ],
  "type": "object"
}

complete_artifact_multipart

Finish multipart upload, content-address bytes, and register artifact metadata.

Capability: artifact:upload

{
  "properties": {
    "kind": {
      "enum": [
        "screenshot",
        "recording",
        "transcript",
        "code_dump",
        "attachment"
      ],
      "type": "string"
    },
    "mime_type": {
      "type": "string"
    },
    "object_key": {
      "type": "string"
    },
    "parts": {
      "items": {
        "properties": {
          "etag": {
            "type": "string"
          },
          "part_number": {
            "type": "integer"
          }
        },
        "required": [
          "part_number",
          "etag"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "upload_id": {
      "type": "string"
    },
    "uploaded_by": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "upload_id",
    "object_key",
    "parts",
    "kind"
  ],
  "type": "object"
}

abort_artifact_multipart

Abort a failed multipart upload.

Capability: artifact:upload

{
  "properties": {
    "object_key": {
      "type": "string"
    },
    "upload_id": {
      "type": "string"
    }
  },
  "required": [
    "upload_id",
    "object_key"
  ],
  "type": "object"
}

get_artifact_metadata

Fetch artifact metadata by sha256 hex digest.

Capability: workspace:read

{
  "properties": {
    "sha256": {
      "maxLength": 64,
      "minLength": 64,
      "type": "string"
    }
  },
  "required": [
    "sha256"
  ],
  "type": "object"
}

search_messages

Full-text, semantic, or hybrid search over a workspace's messages. Returns ranked hits with highlighted snippets.

Capability: search:query

{
  "properties": {
    "author_id": {
      "format": "uuid",
      "type": "string"
    },
    "channel_id": {
      "format": "uuid",
      "type": "string"
    },
    "embedding_model": {
      "description": "Semantic/hybrid only: registered model name (default: active provider).",
      "type": "string"
    },
    "hybrid_weight": {
      "description": "Hybrid only: semantic weight in [0,1] (default 0.5). combined = w*semantic + (1-w)*lexical over normalized scores.",
      "type": "number"
    },
    "kind": {
      "enum": [
        "human",
        "agent"
      ],
      "type": "string"
    },
    "limit": {
      "default": 25,
      "type": "integer"
    },
    "mode": {
      "default": "lexical",
      "enum": [
        "lexical",
        "semantic",
        "hybrid"
      ],
      "type": "string"
    },
    "query": {
      "minLength": 1,
      "type": "string"
    },
    "snippet_only": {
      "default": false,
      "description": "Drop full message body from each hit (keep only the snippet) to save tokens.",
      "type": "boolean"
    },
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "query"
  ],
  "type": "object"
}

register_slash_command

Register a workspace slash command handler (http URL or MCP tool name).

Capability: workspace:write

{
  "properties": {
    "description": {
      "type": "string"
    },
    "handler_kind": {
      "enum": [
        "http",
        "mcp_tool"
      ],
      "type": "string"
    },
    "handler_target": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "name",
    "handler_kind",
    "handler_target"
  ],
  "type": "object"
}

list_slash_commands

List registered slash commands in a workspace.

Capability: workspace:read

{
  "properties": {
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}

register_fsm_hook

Register an FSM hook invoked on matching thread state transitions.

Capability: workspace:write

{
  "properties": {
    "from_state": {
      "enum": [
        "open",
        "in_review",
        "closed",
        "archived"
      ],
      "type": "string"
    },
    "handler_kind": {
      "enum": [
        "http",
        "mcp_tool"
      ],
      "type": "string"
    },
    "handler_target": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "to_state": {
      "enum": [
        "open",
        "in_review",
        "closed",
        "archived"
      ],
      "type": "string"
    },
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id",
    "handler_kind",
    "handler_target"
  ],
  "type": "object"
}

list_fsm_hooks

List registered FSM automation hooks in a workspace.

Capability: workspace:read

{
  "properties": {
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}

get_thread_context

Pack thread messages, edits, references, FSM history, and the workspace glossary for agent prompts. Edits are lean by default (id/editor/timestamp only); pass include_edits=true for full before/after bodies. The glossary (canonical term definitions) is included by default when non-empty; pass include_glossary=false to drop it. Pass as_of=<event_id> to replay the thread as it stood at that event-log id (deterministic over the immutable log; audit / re-ask from before a tangent).

Capability: workspace:read

{
  "properties": {
    "as_of": {
      "description": "Event-log id: reconstruct the thread as it stood at that point (as-of replay). Omit for the live pack.",
      "type": "integer"
    },
    "include_edits": {
      "default": false,
      "description": "Include full body_before/body_after on each edit (heavy); default returns edit metadata only.",
      "type": "boolean"
    },
    "include_glossary": {
      "default": true,
      "description": "Include the workspace glossary (grounding); omitted when empty. Set false for a token-tight pack.",
      "type": "boolean"
    },
    "message_limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    },
    "transition_limit": {
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

snapshot_thread_context

Freeze the assembled context pack (live or as_of) into the content-addressed artifact store — a tamper-evident, deduped record of exactly what the agent was handed. Same params as get_thread_context; returns the artifact (kind=context_snapshot). Requires artifact:upload. Fetch the bytes via the artifact sha.

Capability: artifact:upload

{
  "properties": {
    "as_of": {
      "description": "Event-log id: freeze the thread as it stood at that point. Omit for the live pack.",
      "type": "integer"
    },
    "include_edits": {
      "default": false,
      "type": "boolean"
    },
    "include_glossary": {
      "default": true,
      "type": "boolean"
    },
    "message_limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    },
    "transition_limit": {
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

get_workspace_context

Pack workspace channels, thread contexts (bounded by thread_limit), and the workspace glossary (once at the top level).

Capability: workspace:read

{
  "properties": {
    "include_glossary": {
      "default": true,
      "description": "Include the workspace glossary once at the top level (grounding); omitted when empty. Set false to drop it.",
      "type": "boolean"
    },
    "message_limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "thread_limit": {
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "transition_limit": {
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    },
    "workspace_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}

summarize_thread

Summarize a thread by asking the connected MCP client to sample an LLM (server→client sampling/createMessage over the GET /mcp/streamable stream). Requires a streamable session whose client declared the sampling capability.

Capability: workspace:read

{
  "properties": {
    "instructions": {
      "description": "Optional steer for the summary.",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "thread_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "thread_id"
  ],
  "type": "object"
}

request_approval

Human-in-the-loop gate: ask the human on the connected MCP client to approve or reject an action (server→client elicitation/create over the GET /mcp/streamable stream). Requires a streamable session whose client declared the elicitation capability. Returns {approved, action, content}.

Capability: workspace:read

{
  "properties": {
    "prompt": {
      "description": "what the human is being asked to approve",
      "type": "string"
    },
    "schema": {
      "description": "optional JSON Schema for structured detail the human may supply (MCP requestedSchema)",
      "type": "object"
    }
  },
  "required": [
    "prompt"
  ],
  "type": "object"
}

list_roots

List the roots (filesystem/workspace boundaries) the connected MCP client exposes, via the server→client roots/list request over the GET /mcp/streamable stream. Requires a streamable session whose client declared the roots capability. Returns the client's roots array.

Capability: workspace:read

{
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

Resources

workspace — maidan://workspaces/{id}

Workspace metadata.

channel — maidan://channels/{id}

Channel metadata.

thread — maidan://threads/{id}

Full thread transcript (up to 100 messages).

artifact — maidan://artifacts/{sha256}

Artifact metadata and byte length (body omitted).

Prompts

thread_workflow

Suggested agent steps for a thread based on its FSM state.

Arguments:

[
  {
    "description": "Thread UUID",
    "name": "thread_id",
    "required": true
  }
]