areas

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.

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.

Input

Agents schema

{
  "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.

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.

{
  "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"
}

defaults_update

Patch Area Run defaults. Explicit null or empty string clears a default. Requires company edit access.

{
  "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"
}

delete

Delete an Area. Existing Tasks remain. Requires company edit access.

{
  "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"
}

get

Get one Area by ID, including its instructions (the guidance every Run in the Area receives) and execution defaults.

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Area UUID.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

list

List Areas in the current workspace, each with its instructions.

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

resources_create

Attach a github_repo to an Area so future Runs check it out. Requires company edit access.

{
  "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"
}

resources_delete

Remove a resource from an Area. Requires company edit access.

{
  "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"
}

resources_list

List resources attached to an Area, including github_repo checkouts.

{
  "additionalProperties": false,
  "properties": {
    "area_id": {
      "description": "Area UUID.",
      "type": "string"
    }
  },
  "required": [
    "area_id"
  ],
  "type": "object"
}

resources_update

Update a github_repo resource’s URL, ref, label, or position. Requires company edit access.

{
  "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"
}

Search Areas by title or description.

{
  "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"
}

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.

{
  "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"
}

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.

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.

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

Connect

Contracts and access

Core tools

Agents and managed-Run tools

Advanced tools

Input

Agents schema

Actions

Output

Example

​Input

​Agents schema

​Actions

​Output

​Example

Input

Agents schema

Actions

Output

Example