Design de Capabilities

Uma Capability é a menor habilidade descritível de um sistema: tipada, com permissões verificadas, auditável e igualmente utilizável por humanos e agentes. O MCP-first não começa com telas, mas com essas capabilities. Somente quando o conjunto de capabilities estiver completo é que surgem Webapp, Aplicativo Móvel, CLI e interfaces de Agent como clientes sobre eles.

Os sete blocos construtivos

O MCP-first modela cada capability com sete elementos estruturais.

Resources

Dados e contextos que podem ser lidos. Resources fornecem ao agente contexto processado, não tabelas de banco de dados brutas, mas visões filtradas e orientadas a propósito do estado do sistema.

Tools

Ações que o sistema pode executar. Cada tool tem um Input Schema tipado, um Output Schema, um Schema de Erro e um Schema de Auditoria. Uma tool é o que um botão na webapp apenas representa.

Prompts / Workflows

Fluxos pré-definidos que guiam um agente por processos complexos e de múltiplas etapas. Workflows definem quais tools devem ser invocadas em qual ordem com qual contexto , e onde são esperadas entradas humanas.

Policies

Regras, permissões, níveis de proteção e processos de aprovação. As Policies decidem quem pode ver, invocar e executar autonomamente uma capability. Elas não são uma camada adicionada depois, são parte da definição da capability.

Audit Events

Cada ação gera uma entrada de auditoria: quem, o quê, quando, com qual aprovação, com qual resultado. Audit Events não são uma extensão operacional opcional, mas um componente obrigatório de cada capability.

Human Confirmation Gates

Mecanismos pelos quais o agente deve solicitar ativamente a confirmação do usuário antes de uma ação ser executada. Os Confirmation Gates são declarados na capability , não implementados ad hoc na UI.

Risk Metadata

Cada capability carrega um nível de risco: low, medium, high, critical ou forbidden_for_ai. Esses metadados controlam o Discovery Filtering, a obrigação de confirmação e o Step-up Auth, e estão disponíveis de forma legível por máquina no Tool Contract.

O que cada entidade deve oferecer

Independentemente do domínio de negócio, cada entidade precisa de um conjunto base consistente de capabilities.

Capabilities base por entidade

entity.list Retornar lista filtrada
entity.search Pesquisa full-text com scoping
entity.get Entidade individual com contexto
entity.create Criar nova entidade
entity.update Alterar campos, idempotente
entity.archive Desativar em vez de excluir
entity.audit Recuperar histórico de alterações
entity.permissions Consultar permissões efetivas
entity.related Carregar entidades relacionadas
entity.recommended_next_actions Sugestões de ação para agentes

Action Layer primeiro

Cada função é implementada primeiro como Action na Action Layer central. Somente depois surge o respectivo adaptador de interface.

Action: create_project

Utilizada por:
  Webapp
  Aplicativo Móvel
  MCP Tool
  Worker
  CLI

Com isso, não há implementação duplicada: quando um botão da Webapp invoca create_project e um agente faz o mesmo, ambos usam o mesmo código, as mesmas validações, os mesmos Audit Events.

Build capabilities once. Expose them everywhere.

Claim Central

O servidor MCP é um adaptador

O servidor MCP não contém lógica de negócio. É um adaptador fino entre o cliente do agente e o Action Layer.

Suas responsabilidades:

Discovery, quais tools e resources existem neste contexto?
Schema Exposure, descrição tipada de inputs, outputs e erros
Auth Context Mapping, mapear o token do cliente para o contexto de usuário e tenant
Policy Checks, este agente pode invocar esta tool neste contexto?
Audit Logging, registrar eventos de execução para cada invocação de tool

Inputs e Outputs tipados

Cada tool define quatro schemas:

Schema	Propósito
Input Schema	Quais parâmetros a tool espera, quais tipos, quais campos obrigatórios?
Output Schema	O que a tool retorna em caso de sucesso?
Schema de Erro	Quais códigos de erro são possíveis, `permission_denied`, `confirmation_required`, `policy_violation`?
Schema de Auditoria	O que é registrado no Audit Event?

Sem estruturas JSON soltas. Agentes, assim como compiladores e testes, dependem desses schemas. Outputs não tipados forçam lógica de adivinhação no lado do cliente.

Idempotência

Muitas tools deveriam ser idempotentes: entregar o mesmo resultado para a mesma solicitação, sem gerar duplicatas desnecessárias.

create_download_link(fileId, expiresAt)

Se já existir um link válido com o mesmo fileId e o mesmo expiresAt, o link existente é retornado, nenhum segundo é criado. Isso reduz erros de agentes em retries e torna os workflows mais robustos contra interrupções de rede.