Desenvolva agentes mais seguros com a documentação Flowtly MCP

Como manter-se atualizado

1. Execute o comando de sincronização após atualizações do MCP.
2. Reinicie a sua stack de agentes para incorporar alterações de capacidades.
3. Guarde esta página nos favoritos para as orientações mais recentes do Flowtly MCP.

O que está incluído

• Regras de autenticação, CORS e caching para endpoints MCP.
• 19 namespaces de recursos com operações de listagem/leitura/escrita.
• 8 agentes integrados com controlo de acesso baseado em funções.
• 14 resumos lógicos para análises computadas.
• Payloads JSON-RPC, exemplos de código e dicas de integração.

Início rápido

• Passo 1 — Obter um token: Aceda a Flowtly Workspace → Tokens de Agente e gere um token de cliente.
• Passo 2 — Inicializar: POST para https://mcp.flowtly.eu/mcp com {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Passo 3 — Ler dados: POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Passo 4 — Escrever dados: POST {"jsonrpc":"2.0","id":"write-1","method":"resources/work-times/write","params":{"uri":"/api/work-times","contents":[{"text":"{\"date\":\"2026-04-03\",\"seconds\":3600,\"project\":\"/projects/1\",\"description\":\"Support\"}"}]}}
• Todos os pedidos utilizam Authorization: Bearer <YOUR_TOKEN> e Content-Type: application/json.

Transporte e Autenticação

• URL base (produção): https://mcp.flowtly.eu
• Endpoints: POST /mcp (entrada JSON-RPC), GET /health (verificação de disponibilidade)
• Autenticação: Authorization: Bearer <token> (preferido). Alternativa: variável de ambiente FLOWTLY_API_KEY. Geração de token: workspace.flowtly.eu/user/agent-tokens
• Content-Type: application/json. Body: JSON-RPC 2.0 {"jsonrpc":"2.0","id":"...","method":"...","params":{...}}
• CORS: Credenciais permitidas apenas a partir de https://workspace.flowtly.eu. Nunca combine Access-Control-Allow-Origin: * com Access-Control-Allow-Credentials: true.
• API upstream: https://api.flowtly.eu — o servidor MCP redireciona todos os pedidos para a API REST Flowtly.

initialize

• Negoceia a versão do protocolo, capacidades e namespaces disponíveis.
• Pedido: {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Capacidades de resposta: {"resources":{"list":true,"read":true,"write":true}}
• Namespaces disponíveis: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, budget-groups, budgets, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.

resources/list

• Método: resources/{namespace}/list — namespace predefinido: work-times quando omitido.
• Namespaces (19): work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, budget-groups, budgets, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests, candidate-notes, resource-request-candidates.
• Devolve um array de objetos {uri, name} que descrevem os recursos disponíveis por namespace. Consulte a descrição detalhada de namespaces abaixo.
• Exemplo: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Método: resources/{namespace}/read — namespace predefinido: work-times.
• Parâmetros: uri (obrigatório) — o URI do recurso, ex. /api/work-times.
• allowPrefixes: permite correspondências entre namespaces. Qualquer URI que comece com um prefixo permitido é aceite.
• Resolução de {current}: {current} nos parâmetros de consulta de colaborador resolve automaticamente para /api/employees/me.
• Predefinições automáticas: work-times adiciona date[after]/date[before] (últimos 30 dias), employees adiciona itemsPerPage=200, holidays/vacations adicionam predefinições de paginação.
• Enriquecimento: A leitura de responsibilities segue até 10 links @id para enriquecer campos de título/nome.
• Namespace lógico: devolve resumos computados do lado do servidor em vez de payloads brutos da API.
• Resposta: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Método: resources/{namespace}/write — apenas recursos com allowWrite aceitam escritas.
• Encaminhamento: POST para criação, PATCH (com application/merge-patch+json) quando o URI termina com um ID. Substitua via params.contentType.
• Caminhos de criação: /api/.../create força POST mesmo que um ID esteja presente.
• Convenção IRI: params.uri utiliza caminhos /api/..., mas as referências a entidades dentro de payloads JSON devem usar IRIs upstream (ex. "project": "/projects/1", não "/api/projects/1").
• Namespaces com escrita: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Auxiliares de escrita lógica: resources/logical/write suporta /logical/work-times/log (POST para /api/work-times), /logical/recruiting/resource-requests/update?id=<id> e /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Agentes integrados

• EmployeeAgent (employee): Operações do dia-a-dia — registar horas, consultar ausências, ver atribuições. Acesso: qualquer utilizador autenticado (scope por token/instância).
• ManagerAgent (manager): Apoio ao gestor de projetos/engenharia — taxas, dotação de pessoal, custos, aprovações. Requer: função project_manager ou admin.
• ExecutiveAgent (executive): Resumos executivos — KPIs, orçamentos, agregações, aprovações. Requer: função admin, executive, director, vp ou c-level.
• HRManagerAgent (hr): RH e ausências — saldos de férias, histórico de ausências, feriados da equipa. Acesso: qualquer utilizador autenticado.
• AccountancyAgent (accountancy): Consultas financeiras — listar transações, resumir montantes. Nunca expõe URLs de anexos. Acesso: qualquer utilizador autenticado.
• RecruiterAgent (recruiter): Recrutamento — listar vagas abertas, pesquisar/criar candidatos, associar a vagas, adicionar notas. Requer: função candidates_manager, admin ou recruiter.
• OnboardingAgent (onboarding): Orientação para novos utilizadores — ajuda na configuração, navegação, respostas a "onde encontro X". Acesso: qualquer utilizador autenticado.
• TechAgent (tech): Configuração técnica — pedidos de credenciais MCP/ChatGPT. Gera credenciais de cliente por utilizador após aprovação do administrador. Acesso: aberto a todas as funções (será restringido).
• Seleção de agente: Use employee para tarefas pessoais; hr para ausências/férias; manager para pessoal/custos; executive para KPIs; accountancy para finanças; recruiter para candidatos; onboarding para configuração.
• Modelo de acesso: As verificações de função utilizam as funções/autoridades/permissões do Flowtly. Os agentes restritos recusam ações quando nenhuma função necessária corresponde. Todos os agentes utilizam apenas a ferramenta API MCP — sem serviços externos.

Namespace lógico — resumos computados

• Resumos de horas: /logical/work-times/summary — horas agregadas por colaborador/projeto. Suporta date[after]/date[before] (predefinição dos últimos 7 dias).
• Resumo de colaboradores: /logical/employees/summary — efetivo, departamentos e visão geral de estado.
• Resumo de projetos: /logical/projects/summary — projetos ativos, tipos de faturação e distribuição por cliente.
• Horas por colaborador: /logical/employee-work-times/summary — análise de utilização por colaborador.
• Taxas de projeto: /logical/project-rates/summary — tabelas de taxas e visão geral das taxas de faturação.
• Transações: /logical/transactions/summary — totais de despesas, categorização e tendências.
• Rentabilidade de projetos: /logical/project-profitability/summary — receita vs. custo por projeto.
• Grupos de orçamento: /logical/budget-groups/summary — alocações de grupos de orçamento e estado de consumo.
• Orçamentos: /logical/budgets/summary — utilização individual de orçamentos e alertas.
• Onboarding da empresa: /logical/company-onboarding/status — progresso da configuração do workspace e passos pendentes.
• Vagas abertas: /logical/recruiting/open-roles — pedidos de recursos não preenchidos e pipeline de contratação.
• Candidatos: /logical/recruiting/candidates — distribuição por etapa do pipeline de candidatos.
• Ausências: /logical/holidays — dados agregados de ausências e disponibilidade da equipa.
• Registo de horas (escrita): /logical/work-times/log — POST cria uma entrada de horas via /api/work-times.

Caching e desempenho

• Cache lógica Redis: Cache opcional para leituras lógicas. Pode partilhar o Redis com a API principal para padrões de invalidação.
• Variáveis de ambiente: MCP_LOGICAL_CACHE_ENABLED (ativada automaticamente quando existe URL Redis), MCP_LOGICAL_CACHE_REDIS_URL (alternativas: REDIS_URL, CACHE_REDIS_URL).
• Formato de chave: Prefixo mcp:logical:v1: — com scope por instância + principal, inclui URI lógico normalizado. Configure o prefixo via MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 segundos (24 horas). Configure via MCP_LOGICAL_CACHE_TTL_SECONDS.

Tratamento de erros

• Erro JSON-RPC padrão: {"jsonrpc":"2.0","id":"...","error":{"code":-32000,"message":"Upstream Flowtly API failed","data":{"status":502}}}
• Códigos de erro comuns: -32700 (erro de análise), -32600 (pedido inválido), -32601 (método não encontrado), -32000 (falha da API upstream).
• O campo data.status reflete o código de estado HTTP da API Flowtly upstream quando disponível.

Notas adicionais

• allowPrefixes: Permite que resources/read aceite URIs que começam com prefixos permitidos, habilitando pesquisas entre namespaces.
• Referência OpenAPI: Disponível em public/mcp/openapi.json (copiado para dist/mcp/openapi.json no momento da compilação).
• Contratos de intenção LLM: Padrões de router + manager documentados em docs/llm-intent-architecture.md, implementados em packages/agent/src/intents/contract.ts.
• Paginação: As predefinições são aplicadas automaticamente por namespace. Substitua com parâmetros de consulta explícitos quando necessário.

Referência de namespaces — resources/list por namespace