> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# tasks_watch

> Input, output and examples for the tasks_watch MCP tool.

<Info>Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see [Get started](/essentials/quickstart).</Info>

Watch accessible Tasks from this Melso conversation, a Run's Task or the chat, and resume it when selected events arrive. watch registers or updates a watch and returns at once: end the turn after it; unwatch stops one without cancelling work; list reads this conversation's watches. Watches persist across Runs until unwatch or this conversation closes. Each action accepts only its own fields (\* required): watch(task\_id\*, events, instruction); unwatch(task\_id\*); list.

**Availability:** Managed Runs and Melso conversations; external OAuth excluded.

**Catalog:** Core (`tools/list`).

<Info>Available to managed Runs and Melso conversations. External OAuth connections do not list this tool.</Info>

The live catalog is authoritative: company type, membership, plan, connected apps and execution context can narrow this contract. [Understand access](/mcp/permissions).

## Input

### Agents / Autónomo / Company schema

```json theme={null}
{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "watch",
        "unwatch",
        "list"
      ],
      "type": "string"
    },
    "events": {
      "description": "Defaults to delivered, failed, needs_input, completed, cancelled. PR events apply to linked PRs and identify the commit SHA.",
      "items": {
        "enum": [
          "delivered",
          "failed",
          "needs_input",
          "completed",
          "cancelled",
          "pr_checks_finished",
          "pr_checks_passed"
        ],
        "type": "string"
      },
      "maxItems": 7,
      "minItems": 1,
      "type": "array",
      "uniqueItems": true
    },
    "instruction": {
      "description": "What to do when this conversation resumes.",
      "maxLength": 4000,
      "type": "string"
    },
    "task_id": {
      "description": "Accessible Task UUID or identifier; it need not be a child.",
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "type": "object"
}
```

## Actions

The family schema combines fields for discovery. Each action accepts only its own fields below; add `action` when calling the family.

<AccordionGroup>
  <Accordion title="list">
    List this conversation's persistent Task watches.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {},
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="unwatch">
    Stop this conversation watching a Task. Does not cancel the Task, its Runs, or human interactions.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "task_id": {
          "description": "Accessible Task UUID or identifier; it need not be a child.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "task_id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="watch">
    Watch an accessible Task and resume this Melso conversation when selected events arrive. The subscriber is this conversation: the Run's Task, or the chat. Returns immediately; end the turn after registering. Watches persist across Runs until unwatch or this conversation closes. Repeating the call updates the same watch. Parent links only organize Tasks.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "events": {
          "description": "Defaults to delivered, failed, needs_input, completed, cancelled. PR events apply to linked PRs and identify the commit SHA.",
          "items": {
            "enum": [
              "delivered",
              "failed",
              "needs_input",
              "completed",
              "cancelled",
              "pr_checks_finished",
              "pr_checks_passed"
            ],
            "type": "string"
          },
          "maxItems": 7,
          "minItems": 1,
          "type": "array",
          "uniqueItems": true
        },
        "instruction": {
          "description": "What to do when this conversation resumes.",
          "maxLength": 4000,
          "type": "string"
        },
        "task_id": {
          "description": "Accessible Task UUID or identifier; it need not be a child.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "task_id"
      ],
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Output

Watch registration, removal, or the current conversation’s watch list. Registering a watch returns immediately and does not itself wait for completion.

The result uses MCP `content` blocks; JSON payloads are encoded in text and may also appear in `structuredContent`. Check `isError` before reading a success payload. The server does not currently declare an `outputSchema`, so treat additional fields as extensible. [Result handling](/mcp/results).

## Example

Use a Run token for this managed-context example. External OAuth clients cannot call this tool. Replace example identifiers with values from your own Task. Write actions change data.

```bash theme={null}
curl --fail-with-body https://melso.ai/api/mcp \
  -H "Authorization: Bearer $MELSO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data-binary @- <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tasks_watch",
    "arguments": {
      "action": "list"
    }
  }
}
JSON
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.