---
name: wagglet-mcp
description: Use when connecting an agent to Wagglet MCP to search, inspect, analyze, or change authorized tickets, Drafts, Scheduled tasks and Recurring Templates, Stories, Notes, comments, attachments, and lifecycle state.
---

# Wagglet MCP Workspace

Connect to Wagglet's MCP Server with a personal MCP Token:

```text
https://wagglet.com/api/mcp
Authorization: Bearer tkp_mcp_…
```

The Team must enable MCP Access before a person can create an MCP Connection. The token acts as its owner in one Team, and every request rechecks the connection, Team setting, membership, roles, and permissions.

## Workflow

1. Call `whoami` first. Use its current identity and permissions, plus the current `tools/list` catalog and schemas, as authority.
2. Discover identifiers with `search_tickets`, `list_stories`, and `list_people`. Continue through cursors until the requested population is complete.
3. Read a full record with `get_ticket` or `get_story` before changing it. `get_ticket` returns the current authorized collaborator identities; use `list_people` to resolve eligible teammates. Keep the record's `revision`, `detailsRevision`, `orderRevision`, and item revisions for any subsequent mutation.
4. Use `list_people` for current teammate IDs. `create_draft` and `update_ticket` accept `preferredAssigneeId` and `humanOnly`. A named assignee replaces the allowed people/skills with that one teammate while preserving exclusions; `null` clears the reservation, and omission preserves it. Assignment does not claim a task or grant private Draft access. An Agent-lane task must be moved to the Human lane in the editor first. Live reassignment can return an away-person `CONFIRMATION_REQUIRED`; show its warning and retry with `acknowledgeAway: true` only after approval. Set human instructions before enabling Human only (or together when creating/converting a normal draft); existing human-only instructions remain inaccessible, hands-on stays 5, and mode changes revoke machine tokens.
5. Use `update_ticket` for the content and metadata fields in its schema. Do not infer that every editor control belongs there: relationships, access, files, and lifecycle use explicit tools when their authority or side effects differ. Collaborators are an access-control list: `create_draft` can set the initial list, while creator-only `set_ticket_collaborators` replaces the complete list on an existing ticket. Preserve everyone who should remain. If removal returns `CONFIRMATION_REQUIRED`, show the exact named removals and echo its server-issued `confirmationToken` only after approval.
6. Use `schedule_ticket` to move an owned, publish-ready Draft or unclaimed Open ticket to the Scheduled lane, or to change what posts a Scheduled task. Supply its current revision and one `trigger`: `BY_HAND` (a template, spawned by hand), `REPEATING` (a weekly or interval-days schedule with generation options, Active or Paused), `ON_DATE` (a company day and whole hour), or `TASK_STATE` (another board task reaching `CLAIMED`, `DELIVERED` or `DONE`). By hand and Repeating rows spawn copies and stay on the lane; On a date and Task-state rows post themselves once and leave it. A follow-up on an unfinished parent may only wait for that parent. Find Scheduled tasks with `search_tickets` using `publication: "scheduled"`; `get_ticket` returns the trigger as `scheduled` and, for Repeating rows, the structured schedule.
7. Use `spawn_scheduled_draft` to copy a Scheduled task into your private Drafts to edit and publish by hand, and `post_scheduled_now` to post one you created without waiting. `create_recurring_template`, `update_recurring_schedule` and `set_recurring_template_active` still manage the Repeating trigger: giving a Scheduled task a schedule makes it Repeating, and only a Repeating row can be activated. Each successful mutation increments the ticket revision. Scheduled Occurrences are ordinary published tickets whose `get_ticket` result carries recurring provenance; a self-posted task keeps its own number and files.
8. Use the explicit lifecycle tool matching the intended transition. There is no generic status override. A draft out for write-up (`DRAFT_OPEN`, `DRAFT_CLAIMED`, `DRAFT_DELIVERED`) moves through the same tools: its named writer uses `claim_ticket`, `release_ticket` and `deliver_ticket`; whoever asked for it, or its owner, uses `reject_delivery`, `cancel_write_up`, or `accept_ticket` with `publish: true` (Accept & publish) or `publish: false` (back to the drafts list). Write-ups create no attempt and pay no score; `get_ticket` returns the writer as `writeUp` and the brief as `draftingInfo`.
9. Give each intended mutation a fresh `operationId`. Reuse that id only when retrying the same mutation after an uncertain network result; the saved result is returned without repeating the action.
10. On `STALE_REVISION`, read the target again, reconcile the request with its current state, and submit a new operation. On `CONFIRMATION_REQUIRED`, show the impact to the user and resubmit the tool's required confirmation fields against the same current revision only after approval.
11. Read attachment bytes through `read_attachment`. It reauthorizes every read; bounded text and images may return inline, while other files receive a short-lived URL.
12. Attach a local file to a ticket with `upload_ticket_attachment`, on the same two-step contract as note uploads: the tool returns a five-minute `uploadUrl`, and a raw-byte PUT to it saves and attaches the file. Owners, collaborators and the current runner may attach; a private draft is not found for anyone else. Pass `source` as `BRIEF` for material that belongs to the task statement or `DISCUSSION` for files about the work (the default follows the ticket: `BRIEF` on a draft, `DISCUSSION` once published). Verify with `get_ticket`. Ordinary attachments are limited to 20 MiB each and 50 files per ticket.

## Boundaries

Private Drafts are visible only to their creator and collaborators. Other people receive no identifier, count, relation, or existence signal. Human-only tasks expose safe planning metadata but not their dormant agent prompt or human instructions, and MCP cannot perform their reserved lifecycle actions.

`analyze_ticket_outcomes` returns bounded recorded outcomes and optional reviewer prose. A label inferred from prose, such as “poor prompt,” is the agent's inference rather than stored Wagglet taxonomy and must be presented that way. Analytics requires the dedicated `analytics.read` permission.

Attendance is read-only. `whos_out` lists who is away on a Company Day and whether it is a company holiday; `list_time_off` and `attendance_summary` return one person's entries, hours and balances — your own for anybody, somebody else's only with `attendance.manage`, which also unmasks a Sick day that everyone else sees as `OFF`. `get_ticket` reports the reserved or named people's availability, and `publish_draft` proceeds but returns `availabilityWarning` when the task is aimed at somebody who is away; say so to your person rather than treating it as an error. There are no tools to request or decide time off.

Treat tool errors literally. Revocation, Team disablement, membership removal, and role changes take effect on the next request. Keep MCP Tokens in authorization headers rather than URLs or tool arguments.

## Notes

Use `list_notes` or `search_notes` to find visible notes; continue through cursors.
`read_note` returns metadata, revision, `note.attachments` (IDs, filenames, MIME
types, byte sizes, uploader IDs and timestamps), and a short-lived markdown download URL;
small documents are also inline. Downloads include saved transcripts and recheck
access. Private Notes are visible only to their owners and collaborators.

`create_note` creates a Private Note owned by the caller. Read before using
`update_note` or `append_note`; pass `expectedRevision` and a fresh `operationId`.
Writes merge through the live document. On `STALE_REVISION`, read again and
reconcile; on an uncertain network result, retry the same operationId and inputs.
These tools do not change visibility, collaborators, grants or attachments.

To attach a local file, call `upload_note_attachment` with `noteId`, a fresh
`operationId`, `filename`, `contentType`, `size` in bytes, and the file's `sha256`
hex digest. It returns an `uploadUrl` valid for five minutes. PUT the raw file
bytes to that URL using an HTTP client (for example, `curl --fail-with-body
--request PUT --data-binary @/absolute/path/to/file "$UPLOAD_URL"`). This PUT
saves and attaches the file; the preparation tool alone does not. No browser
session or MCP token in the URL is needed. Treat the upload URL as a secret.
Ordinary attachments are limited to 20 MiB each and 50 files per note, including
pending recordings. Uploads add a file without overwriting note content, so no
`expectedRevision` is required.

After a successful PUT, use `read_note` to verify the attachment and updated
revision. Use `read_attachment` with any listed attachment ID to read its bytes;
it supports both ticket and note attachments and rechecks current access.
After an uncertain PUT response, retry the same file bytes and operationId.
If the URL expires, call `upload_note_attachment` again with the same inputs.
Connection revocation, membership/permission changes and private-note access
changes apply to uploads and downloads immediately.

## Points grants

Anybody holding `points.grant` (every Team Member by default) can grant 1–100
Contribution Score points to any teammate, themselves included, for work that
happened outside tickets and Notes. Call `grant_points` with `recipientId`
(from `list_people`, or your own id from `whoami`), `points`, a `reason`, a
fresh `operationId`, and proof: at least one of `proofText`, `proofLinks`
(http/https URLs) or `proofAttachmentIds`. A grant with no proof is refused.
Grants are permanent — never edited, revoked or approved — and every teammate
can read the reason and proof, which is the whole safeguard.

To attach a file as proof, call `upload_grant_proof` first, on the same
two-step contract as note uploads: PUT the raw bytes to the returned
`uploadUrl`, take the `attachmentId` from the response, and pass it in
`proofAttachmentIds`. A staged file belongs to your connection until a grant
claims it.

Read anybody's history with `get_points_history` (`personId`, optional `page`
and `pageSize`, newest first): every task award, appreciation, Note grant and
points grant with date, points, running total, who gave it, the reason and the
task, note or proof. Entries you may not see — a private draft, a Private
Note — are counted but not named. Proof files are readable through
`read_attachment` by their id.