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

# secrets

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

Vault items: logins, cards, text secrets and files that Runs receive as variables. list never returns values. request asks a person to save a value, so it never passes through chat or a model; send the returned url (a chat sends cta as a button). It opens the request in their Settings → Secrets, signed in, where it waits until they save or dismiss it, and never expires. Saving it wakes this chat, or continues the Task from a Run. update renames an item or changes who can use it; delete removes it. To store a value you already hold, find secrets\_set with tools\_search. Each action accepts only its own fields (\* required): list; update(id\*, area\_ids, name, share); delete(id\*); request(kind\*, area\_ids, cardholder, env\_name, name, note, share, url, username).

**Availability:** Autónomo / Empresa / 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 / Autónomo / Company schema

```json theme={null}
{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "list",
        "update",
        "delete",
        "request"
      ],
      "type": "string"
    },
    "area_ids": {
      "description": "Area UUIDs when share is areas.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "cardholder": {
      "description": "Name on the card, if known.",
      "type": "string"
    },
    "env_name": {
      "description": "Variable name that will hold the value or file path. Required for a file, such as GCP_SERVICE_ACCOUNT.",
      "type": "string"
    },
    "id": {
      "description": "Item UUID or variable name.",
      "type": "string"
    },
    "kind": {
      "enum": [
        "login",
        "card",
        "text",
        "file"
      ],
      "type": "string"
    },
    "name": {
      "description": "request: login or card name such as Stripe, or a text secret's variable name such as OPENAI_API_KEY. update: the new name.",
      "type": "string"
    },
    "note": {
      "description": "One line on why you need it. The request shows it.",
      "type": "string"
    },
    "share": {
      "description": "Who else can use it. private: only you, your Runs and your chat. workspace: every Run in the company. areas: Runs in area_ids. Default private.",
      "enum": [
        "private",
        "workspace",
        "areas"
      ],
      "type": "string"
    },
    "url": {
      "description": "Login website, such as dashboard.stripe.com.",
      "type": "string"
    },
    "username": {
      "description": "Login email or username, if known.",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "type": "object"
}
```

### Managed run / agents / Managed run / company / Managed run / freelancer schema

```json theme={null}
{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "list",
        "request"
      ],
      "type": "string"
    },
    "area_ids": {
      "description": "Area UUIDs when share is areas.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "cardholder": {
      "description": "Name on the card, if known.",
      "type": "string"
    },
    "env_name": {
      "description": "Variable name that will hold the value or file path. Required for a file, such as GCP_SERVICE_ACCOUNT.",
      "type": "string"
    },
    "kind": {
      "enum": [
        "login",
        "card",
        "text",
        "file"
      ],
      "type": "string"
    },
    "name": {
      "description": "request: login or card name such as Stripe, or a text secret's variable name such as OPENAI_API_KEY. update: the new name.",
      "type": "string"
    },
    "note": {
      "description": "One line on why you need it. The request shows it.",
      "type": "string"
    },
    "share": {
      "description": "Who else can use it. private: only you, your Runs and your chat. workspace: every Run in the company. areas: Runs in area_ids. Default private.",
      "enum": [
        "private",
        "workspace",
        "areas"
      ],
      "type": "string"
    },
    "url": {
      "description": "Login website, such as dashboard.stripe.com.",
      "type": "string"
    },
    "username": {
      "description": "Login email or username, if known.",
      "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="delete">
    Delete a Vault item. Its owner or a company admin can delete it.

    OAuth-only.

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

  <Accordion title="list">
    List the Vault items you can use: logins, cards, text secrets and files, with the variable each Run receives. Values are never returned.

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

  <Accordion title="request">
    Ask a person to save a login, card, text secret or file, so the value never passes through chat or a model. Prefill what you know: the site and username of a login, a card's name, the variable name of a secret or file. Send the returned url to the person (as a button with cta in a chat) and stop: it opens the request in their Settings → Secrets, signed in, where it waits until they save or dismiss it. It never expires, and asking again for the same thing returns the same request. Saving it wakes this chat, or continues this Task from a Run.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "area_ids": {
          "description": "Area UUIDs when share is areas.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "cardholder": {
          "description": "Name on the card, if known.",
          "type": "string"
        },
        "env_name": {
          "description": "Variable name that will hold the value or file path. Required for a file, such as GCP_SERVICE_ACCOUNT.",
          "type": "string"
        },
        "kind": {
          "enum": [
            "login",
            "card",
            "text",
            "file"
          ],
          "type": "string"
        },
        "name": {
          "description": "Login or card name such as Stripe, or a text secret's variable name such as OPENAI_API_KEY.",
          "type": "string"
        },
        "note": {
          "description": "One line on why you need it. The request shows it.",
          "type": "string"
        },
        "share": {
          "description": "Who else can use it. private: only you, your Runs and your chat. workspace: every Run in the company. areas: Runs in area_ids. Default private.",
          "enum": [
            "private",
            "workspace",
            "areas"
          ],
          "type": "string"
        },
        "url": {
          "description": "Login website, such as dashboard.stripe.com.",
          "type": "string"
        },
        "username": {
          "description": "Login email or username, if known.",
          "type": "string"
        }
      },
      "required": [
        "kind"
      ],
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="update">
    Rename a Vault item or change who can use it. Its owner or a company admin can change it.

    OAuth-only.

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "area_ids": {
          "description": "Area UUIDs when share is areas.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "id": {
          "description": "Item UUID or variable name.",
          "type": "string"
        },
        "name": {
          "description": "New name.",
          "type": "string"
        },
        "share": {
          "description": "Who else can use it. private: only you, your Runs and your chat. workspace: every Run in the company. areas: Runs in area_ids. Default private.",
          "enum": [
            "private",
            "workspace",
            "areas"
          ],
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Output

Secret metadata, a human entry request, or the update/deletion result. Listing metadata does not reveal secret values.

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": "secrets",
    "arguments": {
      "action": "list"
    }
  }
}
JSON
```


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