# Servidor MCP do Selfcare: como ligar o Claude, o ChatGPT e o Cursor

> Liga um assistente de IA ao Selfcare pelo MCP em https://api.selfcare.work/mcp, com OAuth 2.1 e PKCE e o teu próprio utilizador. Passos para o Claude, o ChatGPT, o Cursor e outros clientes, âmbitos, ferramentas e limites.

O Selfcare tem um servidor MCP (Model Context Protocol) para assistentes de IA. Cada pessoa entra com o seu utilizador Selfcare e o assistente passa a poder consultar o saldo de férias, pedir ausências, registar despesas, deslocações e quilómetros, abrir documentos e tratar aprovações, sempre com as permissões que essa pessoa tem na app.

Versão HTML: https://www.selfcare.work/mcp

## Resumo

- **URL do servidor:** `https://api.selfcare.work/mcp`
- **Transporte:** Streamable HTTP sem estado: cada pedido é um POST com JSON-RPC.
- **Autenticação:** OAuth 2.1 com PKCE (S256), com o utilizador da pessoa. Não há token fixo partilhado.
- **Servidor de autorização:** `https://api.selfcare.work`
- **Registo do cliente:** Dinâmico (RFC 7591): o cliente regista-se sozinho, sem chaves para copiar.
- **Preço:** Incluído em todos os planos, sem custo extra.

## Descoberta e autorização

1. Sem token, um pedido a https://api.selfcare.work/mcp responde 401 com o cabeçalho WWW-Authenticate, que aponta para os metadados do recurso protegido.
2. Metadados do recurso protegido (RFC 9728): https://api.selfcare.work/.well-known/oauth-protected-resource/mcp. Também respondem na raiz, em https://api.selfcare.work/.well-known/oauth-protected-resource, para clientes que os procuram aí.
3. Metadados do servidor de autorização (RFC 8414): https://api.selfcare.work/.well-known/oauth-authorization-server. Indicam os endpoints de autorização, token, revogação e registo.
4. Registo dinâmico do cliente (RFC 7591): https://api.selfcare.work/oauth/register. Só clientes públicos, com PKCE S256 obrigatório.
5. O token é emitido para o recurso https://api.selfcare.work/mcp (RFC 8707) e envia-se no cabeçalho Authorization: Bearer. Um token do MCP não serve na API REST, nem o contrário.

```http
HTTP/2 401
WWW-Authenticate: Bearer realm="selfcare", resource_metadata="https://api.selfcare.work/.well-known/oauth-protected-resource/mcp"
```

## Como ligar

### Claude

1. Em Definições → Conectores, escolhe Adicionar conector personalizado.
2. Dá-lhe um nome (Selfcare) e cola o URL https://api.selfcare.work/mcp.
3. Carrega em Ligar. Abre-se o ecrã de autorização do Selfcare: entra com o teu utilizador, escolhe a empresa e confirma o que o assistente pode fazer.

### Claude Code

1. No terminal, acrescenta o servidor com o comando abaixo.
2. Dentro do Claude Code, corre /mcp e escolhe o servidor selfcare: abre-se o browser para entrares no Selfcare e autorizares.

```bash
claude mcp add --transport http selfcare https://api.selfcare.work/mcp
```

### ChatGPT

1. Em Definições → Apps e conectores, ativa o modo de programador (nas definições avançadas) e escolhe Criar.
2. Cola o URL https://api.selfcare.work/mcp e escolhe OAuth como autenticação.
3. Confirma no ecrã de autorização do Selfcare, como no Claude.

### Cursor

1. Abre as definições do Cursor, secção MCP, e acrescenta o servidor ao mcp.json (do projeto ou global).
2. Na primeira utilização, o Cursor abre o browser para entrares no Selfcare e autorizares.

```json
{
  "mcpServers": {
    "selfcare": { "url": "https://api.selfcare.work/mcp" }
  }
}
```

### Outros clientes MCP

Qualquer cliente que fale MCP por Streamable HTTP e faça OAuth 2.1 com descoberta liga-se da mesma forma:

1. Configura um servidor MCP remoto com o URL https://api.selfcare.work/mcp.
2. O cliente recebe o 401, lê os metadados, regista-se sozinho e abre o browser no ecrã de autorização do Selfcare.
3. Entras com o teu utilizador, escolhes a empresa e aprovas os âmbitos. O ecrã avisa que se trata de um assistente de IA.

### Sem OAuth: chave de API

Um cliente que não faça OAuth pode usar uma chave de API pessoal, criada em Definições → API com os âmbitos das ferramentas que vais usar. A chave é tua: guarda-a fora de repositórios e de ficheiros partilhados.

1. Envia a chave no cabeçalho Authorization, como no exemplo.

```json
{
  "mcpServers": {
    "selfcare": {
      "url": "https://api.selfcare.work/mcp",
      "headers": { "Authorization": "Bearer <a tua chave de API>" }
    }
  }
}
```

## Âmbitos (scopes)

- `me:read`: Quem sou, a empresa, o papel e o resumo do dia.
- `absences:read`: Ausências visíveis, saldo de férias, quem está ausente e a caixa de aprovações.
- `absences:write`: Pedir e cancelar ausências.
- `absences:decide`: Aprovar e rejeitar ausências.
- `expenses:read`: Despesas visíveis e categorias.
- `expenses:write`: Criar despesas, carregar recibos e enviar para aprovação.
- `expenses:decide`: Aprovar e rejeitar despesas.
- `trips:read`: Deslocações e ajudas de custo visíveis.
- `trips:write`: Registar e cancelar deslocações.
- `trips:decide`: Aprovar e rejeitar deslocações.
- `mileage:read`: Mapas de Km's visíveis e as viaturas da pessoa.
- `mileage:write`: Criar mapas, acrescentar percursos, calcular distâncias, enviar e cancelar.
- `mileage:decide`: Aprovar e rejeitar mapas de km.
- `documents:read`: Documentos permitidos pelo MCP e ligações temporárias para os abrir.
- `employees:read`: Diretório de colaboradores e aniversários partilhados.

O âmbito payments:write (marcar como pago ou reverter um pagamento) é sensível e fica fora dos âmbitos que um cliente MCP registado sozinho pode pedir. As ferramentas de pagar só funcionam com uma app registada em Definições → API que declare esse âmbito e com o consentimento explícito de um dono ou de RH.

## Ferramentas por área

### Eu e resumo

- `get_me` (`me:read`): Utilizador, empresa, papel, ficha, equipas que lidera e âmbitos da ligação.
- `get_my_summary` (`me:read`): Saldo de férias, próximas ausências, decisões pendentes, documentos por ler e notificações, numa só chamada.

### Ausências

- `get_vacation_balance` (`absences:read`): Saldo de férias.
- `list_absence_types` (`absences:read`): Tipos de ausência da empresa.
- `list_absences` (`absences:read`): Ausências visíveis.
- `get_absence` (`absences:read`): Uma ausência, sem anexos como atestados.
- `request_absence` (`absences:write`): Pedir férias ou outra ausência.
- `cancel_absence` (`absences:write`): Cancelar um pedido, ou pedir o cancelamento de férias aprovadas.
- `who_is_out` (`absences:read`): Quem está ausente num dia, só com nomes e datas.
- `list_pending_approvals` (`absences:read`): Pedidos à espera da decisão do utilizador (ausências, despesas e deslocações).
- `approve_absence` (`absences:decide`): Aprovar uma ausência que o utilizador pode decidir.
- `reject_absence` (`absences:decide`): Rejeitar uma ausência que o utilizador pode decidir.

### Despesas

- `list_expenses` (`expenses:read`): Despesas visíveis, com estado e data de reembolso.
- `get_expense` (`expenses:read`): Uma despesa, com recibos e estado de reembolso.
- `list_expense_categories` (`expenses:read`): Categorias de despesa.
- `create_expense` (`expenses:write`): Criar uma despesa em rascunho.
- `get_expense_receipt_upload_url` (`expenses:write`): Obter uma ligação para carregar o recibo.
- `add_expense_receipt` (`expenses:write`): Confirmar o recibo carregado, com o valor.
- `submit_expense` (`expenses:write`): Enviar a despesa para aprovação.
- `approve_expense` (`expenses:decide`): Aprovar uma despesa.
- `reject_expense` (`expenses:decide`): Rejeitar uma despesa, com uma nota para a pessoa.

### Ajudas de custo (deslocações)

- `list_business_trips` (`trips:read`): Deslocações visíveis, com a ajuda de custo.
- `get_business_trip` (`trips:read`): Uma deslocação, com estado, decisão e valores.
- `create_business_trip` (`trips:write`): Registar uma deslocação, que segue logo para aprovação.
- `cancel_business_trip` (`trips:write`): Cancelar uma deslocação.
- `approve_business_trip` (`trips:decide`): Aprovar uma deslocação.
- `reject_business_trip` (`trips:decide`): Rejeitar uma deslocação, com uma nota para a pessoa.
- `pay_business_trip` (`payments:write`): Marcar como paga (só com payments:write).
- `revert_business_trip_payment` (`payments:write`): Reverter o pagamento (só com payments:write).

### Mapas de Km's

- `list_mileage_maps` (`mileage:read`): Mapas de km visíveis.
- `get_mileage_map` (`mileage:read`): Um mapa, com cada percurso e os totais.
- `create_mileage_map` (`mileage:write`): Abrir o mapa de um mês.
- `add_mileage_line` (`mileage:write`): Acrescentar um percurso ao mapa.
- `submit_mileage_map` (`mileage:write`): Enviar o mapa para aprovação.
- `cancel_mileage_map` (`mileage:write`): Cancelar o mapa.
- `approve_mileage_map` (`mileage:decide`): Aprovar um mapa.
- `reject_mileage_map` (`mileage:decide`): Rejeitar um mapa, com uma nota para a pessoa.
- `pay_mileage_map` (`payments:write`): Marcar como pago (só com payments:write).
- `revert_mileage_map_payment` (`payments:write`): Reverter o pagamento (só com payments:write).
- `list_my_vehicles` (`mileage:read`): Viaturas do utilizador, com a pré-definida.
- `calculate_distance` (`mileage:write`): Calcular os km de um percurso, se a empresa tiver o serviço de mapas ligado.

### Documentos

- `list_documents` (`documents:read`): Documentos permitidos pelo MCP.
- `get_document_link` (`documents:read`): Ligação temporária (5 minutos) para abrir um documento. O acesso fica registado.

### Colaboradores e equipas

- `search_employees` (`employees:read`): Pesquisar no diretório, como o utilizador o vê na app, com as equipas de cada pessoa e quem as lidera.
- `list_teams` (`employees:read`): As equipas da empresa, com quem lidera cada uma e quantas pessoas tem (o líder conta uma vez).
- `birthdays` (`employees:read`): Aniversários de um mês, só de quem os partilha (dia e mês).

### Prompts

- `request_vacation`: Marcar férias depois de confirmar o saldo.

## Limites e regras

- **O perfil da pessoa manda.** O assistente age como a pessoa que autorizou a ligação, na empresa que ela escolheu. Vê e faz só o que essa pessoa vê e faz na app, com os mesmos papéis e permissões.
- **As aprovações são respeitadas.** Cada ferramenta usa a API do Selfcare, com as regras da app: quem vê, quem decide, «Quem aprova» de cada módulo e idempotência. Um assistente nunca dá a ninguém um poder de decisão que essa pessoa não tenha na app.
- **Sem salários nem IBAN.** Processamento salarial, contratos, remuneração e o IBAN completo nunca saem pelo MCP. Qualquer coisa com forma de IBAN é mascarada antes de sair.
- **Documentos só da lista permitida.** Pelo MCP só se veem o regulamento interno, as políticas e os manuais da empresa e os comprovativos de despesa da própria pessoa. Recibos de vencimento, contratos, documentos de identificação, documentos de saúde, atestados e documentos disciplinares nunca saem.
- **Contabilistas fora.** Contas com o papel de contabilista não podem usar o MCP: o ecrã de autorização recusa e o servidor responde 403.
- **Tudo fica registado.** Cada escrita fica no registo de auditoria da empresa, marcada como vinda do MCP. A pessoa revoga o acesso em Definições → API → Apps autorizadas.

## Perguntas frequentes

### Preciso de uma chave ou de um token para ligar o assistente?

Não. O cliente MCP regista-se sozinho e abre o ecrã de autorização do Selfcare, onde entras com o teu utilizador. A chave de API é só para clientes que não fazem OAuth.

### O assistente vê os dados de toda a empresa?

Vê o mesmo que tu vês na app, e nada mais: o teu papel e as tuas permissões valem também para o assistente.

### O assistente pode ver salários?

Não. Processamento salarial, contratos, remuneração e IBAN completo nunca saem pelo MCP.

### Como desligo o assistente?

Em Definições → API → Apps autorizadas, revoga a ligação do assistente.

### Tem custo?

Não. O servidor MCP está incluído em todos os planos, tal como a API e os webhooks.

## Mais informação

- Documentação para programadores: https://api.selfcare.work/docs#mcp
- API e integrações: https://www.selfcare.work/programadores
- Segurança e RGPD: https://www.selfcare.work/seguranca