> ## 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.

# areas

> Input, output and examples for the areas 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>

Read and manage Areas, their instructions (the guidance every Run in the Area receives), Run defaults and GitHub repo resources. Writes require company edit access, except instructions alone, which any member who can open the Area may set. delete, resources\_delete and defaults\_update remove or clear data. Each action accepts only its own fields (\* required): list; get(id\*); search(query\*, limit, offset); create(title\*, description, icon, idempotency\_key, instructions, resources, sandbox\_size); update(id\*, description, icon, idempotency\_key, instructions, sandbox\_size, sort\_order, title); delete(id\*, idempotency\_key); defaults\_update(id\*, default\_harness, default\_model, default\_service\_tier, default\_thinking\_level, idempotency\_key); resources\_list(area\_id\*); resources\_create(area\_id\*, resource\_type\*, default\_branch\_hint, idempotency\_key, label, position, ref, resource\_ref, url); resources\_update(area\_id\*, resource\_id\*, default\_branch\_hint, idempotency\_key, label, position, ref, resource\_ref, url); resources\_delete(area\_id\*, resource\_id\*, idempotency\_key).

**Availability:** Agents invitation.

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

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

## Input

### Agents schema

```json theme={null}
{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "list",
        "get",
        "search",
        "create",
        "update",
        "delete",
        "defaults_update",
        "resources_list",
        "resources_create",
        "resources_update",
        "resources_delete"
      ],
      "type": "string"
    },
    "area_id": {
      "description": "Area UUID.",
      "type": "string"
    },
    "default_branch_hint": {
      "description": "Optional default branch hint.",
      "type": "string"
    },
    "default_harness": {
      "description": "Harness from workspace_status execution: melso (Melso, no computer) or a Cloud CLI such as codex or claude.",
      "type": "string"
    },
    "default_model": {
      "description": "Harness-native model ID.",
      "type": "string"
    },
    "default_service_tier": {
      "description": "Harness-native service tier.",
      "type": "string"
    },
    "default_thinking_level": {
      "description": "Harness-native thinking level.",
      "type": "string"
    },
    "description": {
      "description": "Short description. Empty clears it on update.",
      "type": "string"
    },
    "icon": {
      "description": "Optional Area icon key: chart-line, layers, dollar-sign, ticket, package, users, briefcase, code, scale, folder. Empty selects folder.",
      "type": "string"
    },
    "id": {
      "description": "Area UUID.",
      "type": "string"
    },
    "idempotency_key": {
      "description": "Optional unique key for this write; reuse only for retries.",
      "type": "string"
    },
    "instructions": {
      "description": "Guidance for agents working in this Area: what it covers, how work is done here, and what to avoid. Markdown. Every Run in the Area receives it. On update it replaces the current instructions; empty clears them.",
      "type": "string"
    },
    "label": {
      "description": "Resource label. Empty clears it on update.",
      "type": "string"
    },
    "limit": {
      "description": "Maximum matches. Defaults to 20.",
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "description": "Skip this many matches.",
      "minimum": 0,
      "type": "integer"
    },
    "position": {
      "type": "integer"
    },
    "query": {
      "description": "Search text, such as engineering or product.",
      "type": "string"
    },
    "ref": {
      "description": "Checkout branch or SHA.",
      "type": "string"
    },
    "resource_id": {
      "description": "Resource UUID.",
      "type": "string"
    },
    "resource_ref": {
      "description": "Full github_repo ref. Used instead of url/ref when supplied.",
      "type": "object"
    },
    "resource_type": {
      "description": "Must be github_repo.",
      "type": "string"
    },
    "resources": {
      "description": "Optional github_repo resources to attach on create.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "label": {
            "description": "Optional label.",
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "ref": {
            "description": "Optional checkout ref.",
            "type": "string"
          },
          "resource_ref": {
            "description": "github_repo ref: url, optional ref, optional default_branch_hint.",
            "type": "object"
          },
          "resource_type": {
            "description": "Must be github_repo.",
            "type": "string"
          },
          "url": {
            "description": "GitHub clone URL. Used when resource_ref is omitted.",
            "type": "string"
          }
        },
        "required": [
          "resource_type"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "sandbox_size": {
      "description": "Sandbox size: standard, large, or xlarge. Must have a verified template available; compute cost is based on CPU and RAM.",
      "type": "string"
    },
    "sort_order": {
      "description": "Display order.",
      "type": "integer"
    },
    "title": {
      "description": "Area title, such as Engineering or Product.",
      "type": "string"
    },
    "url": {
      "description": "GitHub clone URL, such as https://github.com/org/repo.git.",
      "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="create">
    Create an Area with its instructions, the guidance every Run in the Area receives. Requires company edit access. Attach a GitHub repo now or with areas\_resources\_create.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "description": {
          "description": "Optional short description.",
          "type": "string"
        },
        "icon": {
          "description": "Optional Area icon key: chart-line, layers, dollar-sign, ticket, package, users, briefcase, code, scale, folder. Empty selects folder.",
          "type": "string"
        },
        "idempotency_key": {
          "description": "Optional unique key for this create; reuse only for retries.",
          "type": "string"
        },
        "instructions": {
          "description": "Guidance for agents working in this Area: what it covers, how work is done here, and what to avoid. Markdown. Every Run in the Area receives it.",
          "type": "string"
        },
        "resources": {
          "description": "Optional github_repo resources to attach on create.",
          "items": {
            "additionalProperties": false,
            "properties": {
              "label": {
                "description": "Optional label.",
                "type": "string"
              },
              "position": {
                "type": "integer"
              },
              "ref": {
                "description": "Optional checkout ref.",
                "type": "string"
              },
              "resource_ref": {
                "description": "github_repo ref: url, optional ref, optional default_branch_hint.",
                "type": "object"
              },
              "resource_type": {
                "description": "Must be github_repo.",
                "type": "string"
              },
              "url": {
                "description": "GitHub clone URL. Used when resource_ref is omitted.",
                "type": "string"
              }
            },
            "required": [
              "resource_type"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "sandbox_size": {
          "description": "Sandbox size: standard, large, or xlarge. Must have a verified template available; compute cost is based on CPU and RAM.",
          "type": "string"
        },
        "title": {
          "description": "Area title, such as Engineering or Product.",
          "type": "string"
        }
      },
      "required": [
        "title"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="defaults_update">
    Patch Area Run defaults. Explicit null or empty string clears a default. Requires company edit access.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "default_harness": {
          "description": "Harness from workspace_status execution: melso (Melso, no computer) or a Cloud CLI such as codex or claude.",
          "type": "string"
        },
        "default_model": {
          "description": "Harness-native model ID.",
          "type": "string"
        },
        "default_service_tier": {
          "description": "Harness-native service tier.",
          "type": "string"
        },
        "default_thinking_level": {
          "description": "Harness-native thinking level.",
          "type": "string"
        },
        "id": {
          "description": "Area UUID.",
          "type": "string"
        },
        "idempotency_key": {
          "description": "Optional unique key for this edit; reuse only for retries.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="delete">
    Delete an Area. Existing Tasks remain. Requires company edit access.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Area UUID.",
          "type": "string"
        },
        "idempotency_key": {
          "description": "Optional unique key for this delete; reuse only for retries.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get">
    Get one Area by ID, including its instructions (the guidance every Run in the Area receives) and execution defaults.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Area UUID.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list">
    List Areas in the current workspace, each with its instructions.

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

  <Accordion title="resources_create">
    Attach a github\_repo to an Area so future Runs check it out. Requires company edit access.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "area_id": {
          "description": "Area UUID.",
          "type": "string"
        },
        "default_branch_hint": {
          "description": "Optional default branch hint.",
          "type": "string"
        },
        "idempotency_key": {
          "description": "Optional unique key for this create; reuse only for retries.",
          "type": "string"
        },
        "label": {
          "description": "Optional label.",
          "type": "string"
        },
        "position": {
          "type": "integer"
        },
        "ref": {
          "description": "Optional checkout branch or SHA.",
          "type": "string"
        },
        "resource_ref": {
          "description": "Full github_repo ref. Used instead of url/ref when supplied.",
          "type": "object"
        },
        "resource_type": {
          "description": "Must be github_repo.",
          "type": "string"
        },
        "url": {
          "description": "GitHub clone URL, such as https://github.com/org/repo.git.",
          "type": "string"
        }
      },
      "required": [
        "area_id",
        "resource_type"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="resources_delete">
    Remove a resource from an Area. Requires company edit access.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "area_id": {
          "description": "Area UUID.",
          "type": "string"
        },
        "idempotency_key": {
          "description": "Optional unique key for this delete; reuse only for retries.",
          "type": "string"
        },
        "resource_id": {
          "description": "Resource UUID.",
          "type": "string"
        }
      },
      "required": [
        "area_id",
        "resource_id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="resources_list">
    List resources attached to an Area, including github\_repo checkouts.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "area_id": {
          "description": "Area UUID.",
          "type": "string"
        }
      },
      "required": [
        "area_id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="resources_update">
    Update a github\_repo resource's URL, ref, label, or position. Requires company edit access.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "area_id": {
          "description": "Area UUID.",
          "type": "string"
        },
        "default_branch_hint": {
          "description": "Default branch hint.",
          "type": "string"
        },
        "idempotency_key": {
          "description": "Optional unique key for this edit; reuse only for retries.",
          "type": "string"
        },
        "label": {
          "description": "Optional label. Empty clears it.",
          "type": "string"
        },
        "position": {
          "type": "integer"
        },
        "ref": {
          "description": "Checkout branch or SHA.",
          "type": "string"
        },
        "resource_id": {
          "description": "Resource UUID.",
          "type": "string"
        },
        "resource_ref": {
          "description": "Full github_repo ref. Used instead of url/ref when supplied.",
          "type": "object"
        },
        "url": {
          "description": "GitHub clone URL.",
          "type": "string"
        }
      },
      "required": [
        "area_id",
        "resource_id"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="search">
    Search Areas by title or description.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "limit": {
          "description": "Maximum matches. Defaults to 20.",
          "maximum": 50,
          "minimum": 1,
          "type": "integer"
        },
        "offset": {
          "description": "Skip this many matches.",
          "minimum": 0,
          "type": "integer"
        },
        "query": {
          "description": "Search text, such as engineering or product.",
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="update">
    Update an Area's title, description, icon, sort order or instructions. Instructions replace the Area's guidance; any member who can open the Area may write them. The other fields require company edit access.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "description": {
          "description": "Short description. Empty clears it.",
          "type": "string"
        },
        "icon": {
          "description": "Area icon key: chart-line, layers, dollar-sign, ticket, package, users, briefcase, code, scale, folder. Empty selects folder.",
          "type": "string"
        },
        "id": {
          "description": "Area UUID.",
          "type": "string"
        },
        "idempotency_key": {
          "description": "Optional unique key for this edit; reuse only for retries.",
          "type": "string"
        },
        "instructions": {
          "description": "Guidance for agents working in this Area: what it covers, how work is done here, and what to avoid. Markdown. Every Run in the Area receives it. Replaces the current instructions; empty clears them.",
          "type": "string"
        },
        "sandbox_size": {
          "description": "Sandbox size: standard, large, or xlarge. Must have a verified template available; compute cost is based on CPU and RAM.",
          "type": "string"
        },
        "sort_order": {
          "description": "Display order.",
          "type": "integer"
        },
        "title": {
          "description": "Area title.",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Output

Area records, resource records, or the selected edit’s response. Definition writes may include a `company_commit_sha`; deletion is a definition change.

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 an OAuth access token issued for this MCP resource (a Run token for Run-only tools). Replace example identifiers with values from your own account. 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": "areas",
    "arguments": {
      "action": "list"
    }
  }
}
JSON
```


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