---
title: MCP
description: >-
  MCP remoto em https://api.linkdash.dev/mcp. Inicie sessão com OAuth a partir
  do Claude, ChatGPT, Cursor e Codex, ou utilize uma chave de API.
sidebar:
  label: MCP
  order: 5
---
MCP remoto em `https://api.linkdash.dev/mcp`. Adicione o URL ao cliente e inicie sessão com a sua conta Linkdash. Para agentes que funcionam sem uma pessoa num browser, utilize antes uma [chave de API](#automation-and-headless-agents). Markdown simples: [mcp.md](https://linkdash.dev/mcp.md).

## Ligar

Indique ao cliente apenas o URL `https://api.linkdash.dev/mcp`. O cliente abre o início de sessão do Linkdash e, depois, um ecrã de consentimento que identifica a aplicação e o site para onde regressa. Autorize e o cliente recebe um token para a sua conta.

- **claude.ai e Claude Desktop:** abra [o Linkdash no diretório de conectores](https://claude.ai/directory/linkdash) (ou Customize → Connectors e procure Linkdash) e clique em **Connect**.
- **ChatGPT:** o Linkdash estará disponível em breve no diretório de plugins do ChatGPT. Até lá, em [Plugins](https://chatgpt.com/plugins), escolha **+** → **Add custom MCP server**, introduza o URL acima e escolha OAuth.
- **Claude Code:** `claude mcp add --transport http linkdash https://api.linkdash.dev/mcp` e, depois, `claude mcp login linkdash` (ou `/mcp` numa sessão).
- **Cursor:** [Adicionar ao Cursor](https://cursor.com/install-mcp?name=linkdash&config=eyJ1cmwiOiJodHRwczovL2FwaS5saW5rZGFzaC5kZXYvbWNwIn0%3D) instala-o com um clique; depois, inicie sessão quando o Cursor o pedir. Em alternativa, adicione o servidor ao `mcp.json` com `"url"` e sem `headers`.
- **Codex:** `codex mcp add linkdash --url https://api.linkdash.dev/mcp` e, depois, `codex mcp login linkdash`.

A aplicação obtém o mesmo acesso que uma chave de API. As aplicações ligadas são apresentadas em [Painel → Chaves de API](https://linkdash.dev/dashboard/keys), onde **Desligar** revoga o acesso de imediato.

## Automatização e agentes headless

Iniciar sessão requer uma pessoa num browser. Para tarefas de CI, agentes agendados, servidores e código que chama o MCP diretamente, envie antes uma [chave de API](https://linkdash.dev/dashboard/keys): `Authorization: Bearer ldash_...`, as mesmas chaves da [API HTTP](/pt/api).

**Cursor** (`~/.cursor/mcp.json` ou `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "linkdash": {
      "url": "https://api.linkdash.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:LINKDASH_API_KEY}" }
    }
  }
}
```

**Claude Code:** `claude mcp add --transport http linkdash https://api.linkdash.dev/mcp --header "Authorization: Bearer $LINKDASH_API_KEY"` (em JSON, é necessário `"type": "http"`).

**Codex:** `codex mcp add linkdash --url https://api.linkdash.dev/mcp --bearer-token-env-var LINKDASH_API_KEY`

**OpenCode:** `opencode mcp add linkdash --url https://api.linkdash.dev/mcp --header Authorization="Bearer $LINKDASH_API_KEY"`

Local: URL `.site` do Convex + `/mcp`.

## Ficheiros

Não envie bytes através do JSON do MCP. Gere um URL (`{uploadUrl,storageId}`), faça PUT do ficheiro a partir do host e, depois, crie o link:

```bash
curl https://api.linkdash.dev/v1/uploads \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"fileSize":12345}'

curl -X PUT -H "Content-Type: video/mp4" --data-binary @clip.mp4 "$uploadUrl"

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"storageId":"…","fileName":"clip.mp4","fileType":"video/mp4","fileSize":12345}'
```

Ferramentas MCP: `files_upload_url` devolve `{uploadUrl,storageId}` → o host faz PUT para `uploadUrl` → `links_create` com esse `storageId`. Cartão de pré-visualização opcional: `previewName`, `previewDescription`, `previewImageStorageId` (mesmo carregamento). O parâmetro opcional `maxOpenings` coloca o link em pausa após esse número de aberturas; `links_update` pode aumentá-lo ou passar `clearMaxOpenings`. Não mostre o `uploadUrl` ao utilizador.

## Ferramentas

| CLI | HTTP | MCP |
| --- | --- | --- |
| `auth whoami` | `GET /me` | `whoami` |
| `links list` | `GET /links` (`?q=&tag=&kind=&status=&folder=&limit=&cursor=`) | `links_list` |
| `links get <id>` | `GET /links/:id` (`?domain=`) | `links_get` |
| `links create --url/--file/--text/--folder` | `POST /links` | `links_create` |
| `links update <id>` | `PATCH /links/:id` | `links_update` |
| `links move <id>` | `POST /links/:id/move` | `links_move` |
| `links copy <id>` | `POST /links/:id/copy` | `links_copy` |
| `links delete <id>` | `DELETE /links/:id` (`?contents=keep\|delete`) | `links_delete` |
| `links share <id> --email <e>` | `POST /links/:id/shares` | `links_share` |
| `links unshare <id> --email <e>` | `DELETE /links/:id/shares/:email` | `links_unshare` |
| `links shares <id>` | `GET /links/:id/shares` | `links_shares` |
| `links shares` (sem id) | `GET /shares` | `links_shares` (sem `id`) |
| `links shared` | `GET /shared` | `links_shared` |
| `links leave <_id \| share URL>` | `DELETE /shared/:id` | `links_leave` |
| `links_share_role` | `{ id, email, role }` → `{ id, email, role }` (viewer ou editor) |
| `links_unlock` | `{ id, variant?, password?, variantPassword? }` → o destino; desbloqueia uma variante protegida por palavra-passe para um editor durante 30 minutos |
| `links_activity` | `{ id, limit?, cursor? }` → `{ items: [{ action, detail?, actor, _creationTime }], cursor }` |
| `links role <id> --email <e> --role viewer\|editor` | `PATCH /links/:id/shares/:email` | `links_share_role` |
| `links unlock <_id \| share URL>` | `POST /links/:id/unlock` | `links_unlock` |
| `links activity <id>` | `GET /links/:id/activity` | `links_activity` |
| `links reset-link <id>` | `POST /links/:id/reset-link` | `links_update` (`resetShareLink: true`) |
| `links stats --last 24h` | `GET /links/:id/stats?last=24h` | `links_stats` |
| `links export` | `GET /links/export` | `links_export` |
| `links import` | `POST /links/import` | `links_import` |
| `links variants list <id>` | `GET /links/:id/variants` | `variants_list` |
| `links variants add <id>` | `POST /links/:id/variants` | `variants_add` |
| `links variants update <id> <name>` | `PATCH /links/:id/variants/:name` | `variants_update` |
| `links variants remove <id> <name>` | `DELETE /links/:id/variants/:name` | `variants_remove` |
| (PUT do host após gerar o URL) | `POST /uploads` | `files_upload_url` |
| | `DELETE /uploads/:storageId` | `files_discard` |
| `webhooks list/create/get/rotate/delete` | `GET/POST /webhooks`, `GET/DELETE /webhooks/:id`, `POST /webhooks/:id/rotate` | `webhooks_*` |
| `domains list/add/connect/verify/remove` | `GET/POST /domains`, `GET /domains/:host/connect`, `POST /domains/:host/verify`, `DELETE /domains/:host` | `domains_*` |

## Pastas

Uma pasta é um link que lista os itens nela colocados. Consulte [Pastas](/pt/folders) para conhecer o modelo.

| Ferramenta | Entrada |
| --- | --- |
| `links_create` | `{ kind: "folder", name, … }` cria uma pasta; qualquer criação aceita `folder` (slug) e `folderDomain?` para criar dentro de uma pasta. A resposta inclui `folder` |
| `links_list` | Uma página, `{ items, cursor }` (`limit` 1-100, predefinição 50; volte a passar `cursor` até ser `null`). `q` procura por palavras; `folder: "<slug>"` lista o que está diretamente dentro da pasta; `folder: "root"` lista o nível superior; `kind` aceita também `folder`. As linhas incluem `folder` e as linhas de pastas incluem `items` |
| `links_move` | `{ id, domain?, folder: string \| null, folderDomain? }` → `{ id, folder }` |
| `links_copy` | `{ id, domain? }` → `{ id, url, access, kind, folder }` (mesmo acesso, novo URL de partilha, sem pessoas) |
| `links_delete` | `contents?: "keep" \| "delete"` para pastas (predefinição `keep`) |

`links_export` / `links_import` acrescentam as colunas `folder` e `access`, e as linhas com `kind` `folder` criam pastas.

## Acesso e partilha

Os novos links e pastas são restritos: `url` é `https://linkdash.dev/s/<token>`, que só o titular e as pessoas com quem o partilha podem abrir. Passe `access` em `links_create` ou `links_update`: `restricted` (predefinição), `link` (qualquer pessoa com o URL de partilha) ou `public` (qualquer pessoa, no URL curto). Peça `access: "public"` quando o link se destinar a ser publicado. Consulte [Partilha e acesso](/pt/sharing).

| Ferramenta | Entrada |
| --- | --- |
| `links_share` | `{ id, domain?, emails: string[] (1–50), role? }` → `{ id, url, access, invited, alreadyShared }` |
| `links_unshare` | `{ id, domain?, email }` → `{ id, email, removed: true }` |
| `links_shares` | `{ id, domain? }` → `{ id, access, url, people: [{ email, role, accepted, invitedAt, viaFolder? }] }`; `{ limit?, cursor? }` → uma página com tudo o que foi partilhado, `{ items, cursor }`, cada item com `people` |
| `links_shared` | `{ limit?, cursor? }` → uma página de itens que outras pessoas partilharam com o utilizador, `{ items, cursor }`, com o `url` para abrir cada um |
| `links_leave` | `{ id }` (o `_id` ou o URL de partilha de `links_shared`) → `{ _id, left: true }` |
| `links_update` | `access?` altera quem pode abrir o link; `resetShareLink: true` emite um novo URL de partilha (o antigo deixa de funcionar) |

Em todas as respostas, `url` é o URL de partilha, exceto se o link for público, caso em que é o URL curto. Partilhar, deixar de partilhar, alterar o acesso e repor o link contam, cada um, como um evento; sair não conta.

## Variantes

Cada link é um contentor de uma ou mais **variantes**: conteúdo (`url` | `file` | `text`) com o seu próprio controlo de acesso (`password`, `starts`, `expires`, `maxOpenings`, em pausa), um `weight` e condições de visitante `when` opcionais. Sem `variants`, um link tem uma variante chamada `main`. O controlo de acesso do link prevalece sobre o das variantes. Cada visitante recebe uma variante: as variantes cujo `when` corresponde formam o conjunto (caso contrário, as incondicionais) e, depois, é feita uma escolha ponderada; `sticky` (predefinição `true`) mantém um visitante recorrente na mesma variante e `restartSplit` volta a baralhar a distribuição. O `kind` do link é `group` quando tem várias variantes; o `status` do link é `mixed` quando as variantes diferem. Máximo de 20 variantes por link. Formatos: [API HTTP](/pt/api#variantes).

`links_create` aceita `variants: [{ name, url | text | storageId (+ fileName, fileType, fileSize), password?, starts?, expires?, maxOpenings?, utm?, weight?, when? }]` em vez da forma abreviada, além de `sticky` e `forwardParams`. `links_update` aceita `sticky`, `forwardParams` e `restartSplit`. `links_list` filtra por `kind` (acrescenta `group`) e `status` (acrescenta `mixed`). `links_stats` devolve os totais de `variants`. `links_export` / `links_import` utilizam o CSV de variantes (uma linha por variante).

| Ferramenta | Entrada |
| --- | --- |
| `variants_list` | `{ id, domain? }` |
| `variants_add` | `{ id, domain?, name, url \| text \| storageId (+ fileName, fileType, fileSize), password?, starts?, expires?, maxOpenings?, utm?, weight?, when? }` |
| `variants_update` | `{ id, name, domain?, newName?, url?, text?, storageId?, password?, clearPassword?, starts?, clearStarts?, expires?, clearExpires?, maxOpenings?, clearMaxOpenings?, status?, weight?, when?, clearWhen?, utm? }` |
| `variants_remove` | `{ id, name, domain? }` |

Chaves de `when`: `countries`, `devices`, `os`, `browsers`, `languages`, `referrerHosts` (arrays de strings; todas as chaves definidas têm de corresponder), além de `params`.

**Regras de parâmetros de consulta.** `when.params` é um array de até 10 regras aplicadas à query string do visitante; todas as regras têm de se verificar: `{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] }`. `op`: `equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in` (`value` é uma lista separada por `|`) | `exists` | `missing` (sem `value` nos dois últimos). As chaves distinguem maiúsculas de minúsculas e os valores são comparados de forma exata. Os valores dos parâmetros nunca são guardados nas estatísticas.

**Reencaminhar parâmetros de consulta.** `forwardParams` (booleano em `links_create` / `links_update`, predefinição `false`) acrescenta toda a query string do visitante às variantes de URL; os valores do visitante substituem os guardados, incluindo `utm`. Aplica-se apenas a variantes de URL. Trata-se de encaminhamento, não de controlo de acesso.

`auth create` / `auth login` / `auth logout` não são ferramentas MCP. Correspondência: [api.md](https://linkdash.dev/api.md).
