Ferramentas MCP — Visão geral

Direitos de acesso

As ferramentas MCP estão atribuídas a três níveis de scope:

Scope	Significado
`read`	Acesso apenas de leitura; sem criação, edição ou eliminação
`write`	Leitura e escrita de fontes, canais e Inbox; sem acesso às definições da equipa
`admin`	Acesso total ao MCP, incluindo as definições da equipa

Nas ligações OAuth, o scope escolhido durante a autorização limita as ferramentas que podem ser chamadas. Nos tokens de API, o papel do token define o nível máximo de acesso.

Seleção do Workspace

O servidor MCP está em https://picasi.app/mcp, sem Workspace no endereço.

Autenticação	Workspace
Token de API	fixo, o Workspace do token; não é preciso nenhum parâmetro
OAuth	todos os Workspaces da conta; cada chamada precisa de `workspace_id`

Com OAuth, list_workspaces devolve os valores possíveis. Sem workspace_id a chamada é recusada.

Ferramentas de leitura

Todas as ferramentas de leitura exigem, no mínimo, o scope read.

`search_updates`

Pesquisa Updates por termos de pesquisa, fontes, tags e período.

Scope necessário: read

Parâmetro	Tipo	Descrição
`query`	String	Termo de pesquisa de texto completo (opcional)
`source_id`	String	Updates de uma fonte específica (opcional)
`tags`	Array	Tags de tema pelos quais se filtra (opcional)
`folder`	String	`inbox`, `saved` ou `dropped` (opcional)
`source_ownership`	String	`all` (padrão), `own` (apenas fontes próprias) ou `competitor` (apenas fontes externas)
`limit`	Integer	Número de resultados (padrão: 20, máximo: 100)

O filtro source_ownership utiliza o campo is_own da fonte. É o equivalente ao filtro Ownership na UI da Inbox e permite que o assistente de IA analise especificamente apenas a própria presença ou apenas os concorrentes.

`get_update_details`

Devolve o conteúdo completo de um único Update.

Scope necessário: read

Parâmetro	Tipo	Descrição
`update_id`	String	ID do Update

`list_sources`

Enumera todas as fontes do Workspace.

Scope necessário: read

Parâmetro	Tipo	Descrição
`is_own`	Boolean	`true` = apenas fontes próprias, `false` = apenas concorrentes, omitir = todas

Cada fonte devolvida contém o campo is_own, para que os assistentes de IA possam separar a própria presença dos concorrentes sem terem de fazer um segundo pedido.

A cada canal juntam-se três campos que convém distinguir:

Campo	Significado
`monitoring_active`	O interruptor do canal: ligado ou desligado. Não é um estado de saúde.
`state`	O estado da recolha: `healthy`, `degraded`, `broken`, `quarantined` ou `paused`. Os canais de e-mail não são recolhidos, recebem; indicam `receiving`, `stale` ou `waiting`. `null` significa que ainda não há recolha associada.
`last_checked`	A última tentativa de recolha; nos canais de e-mail, a última mensagem recebida.

Para o diagnóstico completo de um canal em concreto existe get_channel_status.

`list_reports`

Enumera os relatórios disponíveis.

Scope necessário: read

Parâmetro	Tipo	Descrição
`type`	String	`summary`, `feedback`, `list`, `linkedin_post`, `conversation_starters` (opcional)
`limit`	Integer	Número (padrão: 10)

`get_report`

Devolve o conteúdo completo de um relatório.

Scope necessário: read

Parâmetro	Tipo	Descrição
`report_id`	String	ID do relatório

`get_team_context`

Devolve o contexto de IA do Workspace: metadados da equipa (nome, idioma, fuso horário), URL do site, documentos de contexto e a configuração de Ownership.

Scope necessário: read

Sem parâmetros obrigatórios.

A resposta contém, no bloco context:

website_url — URL da organização registada
is_own_sources_configured — true assim que pelo menos uma fonte estiver marcada como própria
own_sources_count — número de fontes próprias

Os assistentes de IA só devem propor comparações de voice-share ou momentum quando is_own_sources_configured for true — caso contrário, falta a base de comparação.

`list_tags`

Enumera todas as tags do Workspace.

Scope necessário: read

Parâmetro	Tipo	Descrição
`type`	String	`sources`, `channels`, `updates` (opcional)

`get_update_statistics`

Conta Updates em vez de os listar. Aceita os mesmos filtros que search_updates e não tem o limite de 100 resultados.

Scope necessário: read

Parâmetro	Tipo	Descrição
`group_by`	String	`source` (predefinido), `source_tag`, `update_tag`, `day`, `week`, `month`, `quarter`
`compare_previous_period`	Boolean	Conta também o período anterior com a mesma duração e indica a diferença
`query`	String	Termo de pesquisa em texto integral (opcional)
`source_id`	String	Limitar a uma fonte (opcional)
`source_tags`	Array	Tags de fonte (opcional)
`update_tags`	Array	Tags temáticas (opcional)
`source_ownership`	String	`all` (predefinido), `own` ou `competitor`
`platform`	String	Limitar a uma plataforma, p. ex. `linkedin` (opcional)
`folder`	Array	`inbox`, `saved`; por predefinição ambos
`days`	Integer	Período em dias, de 1 a 365 (predefinido: 30)
`date_from`, `date_to`	String	Período como data, em vez de `days`

Não é possível agrupar por plataforma. Os Updates descartados e os do Overflow não são contados.

`get_channel_status`

Devolve o estado de um canal: última recolha, último êxito, último erro, número de falhas seguidas, próxima tentativa prevista e o número de Updates desse canal.

Scope necessário: read

Parâmetro	Tipo	Descrição
`channel_id`	String	ID do canal, de `list_sources` com `include_channels=true`

`discover_channels`

Analisa um site e comunica os canais que poderiam ser acompanhados. Não cria nada.

Scope necessário: read

Parâmetro	Tipo	Descrição
`url`	String	Site a analisar (opcional se `source_id` estiver definido)
`source_id`	String	Usa o site desta fonte e marca os canais que ela já tem

`list_workspaces`

Lista os Workspaces da conta autenticada com workspace_id, nome e papel.

Scope necessário: nenhum; a ferramenta está aberta a qualquer ligação

Sem parâmetros.

Ferramentas de relatório

`create_report`

Cria um relatório a partir dos Updates que correspondem a um filtro. Os filtros são os mesmos de search_updates.

A geração corre em segundo plano: a chamada devolve logo um request_id. get_report_status diz em que ponto está, get_report lê o relatório terminado.

Scope necessário: read

Parâmetro	Tipo	Descrição
`type`	String	Obrigatório. `summary`, `feedback`, `list` ou `conversation_starters`
`title`	String	Nome do relatório (opcional)
`instructions`	String	Foco para a IA (opcional)
`language`	String	Código de idioma, p. ex. `de`; por predefinição o idioma do Workspace
`query`	String	Termo de pesquisa em texto integral (opcional)
`source_ids`	Array	Limitar a estas fontes (opcional)
`source_tags`	Array	Tags de fonte (opcional)
`source_tags_mode`	String	`AND` ou `OR`
`update_tags`	Array	Tags temáticas (opcional)
`update_tags_mode`	String	`AND` ou `OR`
`source_ownership`	String	`all`, `own` ou `competitor`
`platform`	String	Limitar a uma plataforma (opcional)
`folder`	Array	Pastas da base de dados; por predefinição `inbox` e `saved`
`days`	Integer	Período em dias, de 1 a 365 (predefinido: 30)
`date_from`, `date_to`	String	Período como data, em vez de `days`

`get_report_status`

Devolve em que ponto está um relatório encomendado com create_report.

Scope necessário: read

Parâmetro	Tipo	Descrição
`request_id`	String	O `request_id` de `create_report`

Estado	Significado
`queued`	à espera na fila
`running`	a ser gerado
`ready`	terminado; lê-o com `get_report` e o `report_id`
`empty`	terminado, mas nenhum Update correspondia aos filtros
`failed`	interrompido; o motivo está na resposta

Ferramentas de escrita

Todas as ferramentas de escrita exigem, no mínimo, o scope write.

`create_source`

Cria uma nova fonte.

Scope necessário: write

Parâmetro	Tipo	Descrição
`url`	String	URL do site da fonte
`name`	String	Nome interno
`tags`	Array	IDs de tags (opcional)

`update_source`

Altera o nome, o URL ou as tags de uma fonte existente.

Scope necessário: write

Parâmetro	Tipo	Descrição
`source_id`	String	ID da fonte
`name`	String	Novo nome (opcional)
`url`	String	Novo URL (opcional)

`delete_source`

Elimina uma fonte, incluindo todos os canais e Updates.

Scope necessário: write

Parâmetro	Tipo	Descrição
`source_id`	String	ID da fonte

`create_channel`

Cria um canal manualmente.

Scope necessário: write

Parâmetro	Tipo	Descrição
`source_id`	String	ID da fonte superior
`url`	String	URL do canal
`name`	String	Nome do canal (opcional)

`update_channel`

Altera o nome ou a descrição de um canal.

Scope necessário: write

Parâmetro	Tipo	Descrição
`channel_id`	String	ID do canal
`name`	String	Novo nome (opcional)

`delete_channel`

Elimina um canal.

Scope necessário: write

Parâmetro	Tipo	Descrição
`channel_id`	String	ID do canal

`toggle_channel`

Ativa ou desativa um canal.

Scope necessário: write

Parâmetro	Tipo	Descrição
`channel_id`	String	ID do canal
`active`	Boolean	`true` = ativo, `false` = inativo

`create_tag`

Cria um nova tag.

Scope necessário: write

Parâmetro	Tipo	Descrição
`name`	String	Nome da tag
`type`	String	`sources`, `channels` ou `updates`
`description`	String	Descrição para o KI-Tagging (opcional)

`update_tag`

Altera o nome ou a descrição de uma tag.

Scope necessário: write

Parâmetro	Tipo	Descrição
`tag_id`	String	ID da tag
`name`	String	Novo nome (opcional)
`description`	String	Nova descrição de IA (opcional)

`update_update_state`

Move Updates entre as pastas do Workspace.

Scope necessário: write

Parâmetro	Tipo	Descrição
`update_ids`	Array	IDs de Updates, no máximo 100 por chamada
`folder`	String	`inbox`, `saved` ou `dropped`

O estado vale por Workspace e não altera o Update em si. A resposta comunica cada ID em separado.

`tag_update`

Atribui aos Updates tags temáticas já existentes.

Scope necessário: write

Parâmetro	Tipo	Descrição
`update_ids`	Array	IDs de Updates, no máximo 100 por chamada
`tags`	Array	Tags como slug, ID ou nome
`mode`	String	`add` (predefinido) mantém as tags existentes, `replace` define exatamente estas

Só são admitidas tags com applies_to = updates; uma tag de fonte é recusada. Cria primeiro as tags em falta com create_tag.

`untag_update`

Retira tags temáticas dos Updates.

Scope necessário: write

Parâmetro	Tipo	Descrição
`update_ids`	Array	IDs de Updates, no máximo 100 por chamada
`tags`	Array	Tags a retirar, como slug, ID ou nome

Só é retirada a atribuição deste Workspace. A tag em si mantém-se.

`refresh_source_channels`

Volta a executar a deteção de canais para uma fonte existente.

Scope necessário: write

Parâmetro	Tipo	Descrição
`source_id`	String	ID da fonte
`create_detected`	Boolean	`false` (predefinido) apenas comunica, `true` cria os canais em falta

Os canais existentes não são criados em duplicado; um canal desativado conta como existente. Os canais novos começam a recolha por si.

Tópicos relacionados

MCP — Usar o Picasi no assistente de IA Contexto: o que é o MCP, níveis de scope OAuth e conceito de segurança.

Ligar o Picasi ao Claude Code Criar API-Token e configurá-lo no Claude Code.

Ligar o Picasi ao Claude.ai Configurar a ligação OAuth para o Claude.ai.