Documentação

MCP Fusion/Protocol and runtime/Introspecção

Introspecção

Pergunte à IA sobre a Vinkius

Faça um conector descrever a si próprio: o cartão do servidor no caminho conhecido, o manifesto mcpfusion filtrado por RBAC, os metadados por ação e os contratos por trás do lockfile.

Um conector que consegue se descrever é mais fácil de operar, auditar e integrar. O MCP Fusion expõe três superfícies de introspecção: um cartão de servidor estático, um manifesto dinâmico atualizado e uma API de metadados no processo.

O cartão do servidor

Disponível em /.well-known/mcp/server-card.json em http e stateless, compilado uma vez na inicialização:

json
{
  "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1",
  "version": "1.0",
  "protocolVersion": "2026-07-28",
  "serverInfo": { "name": "billing", "version": "1.4.0", "title": "Billing connector" },
  "transport": { "type": "streamable-http", "endpoint": "/mcp" },
  "capabilities": { "tools": {}, "prompts": {}, "resources": {} },
  "tools": [{ "name": "billing", "description": "...", "tags": ["finance"] }]
}

As capacidades são preenchidas a partir do que o servidor realmente registrou, portanto o cartão não anuncia uma superfície inexistente. Ele é servido somente para leitura, sem sessão e com um cabeçalho de cache público de cinco minutos. Clientes de descoberta e sistemas de monitoramento leem o cartão sem jamais abrir uma conexão MCP.

O manifesto dinâmico

Ative-o para que o conector publique um recurso descrevendo a si próprio:

typescript
attachToServer(server, {
  introspection: {
    enabled: true,
    uri: 'mcpfusion://manifest.json',
    filter: (manifest, ctx) => stripInternal(manifest, ctx.userRole),
  },
});

O manifesto traz a identidade do servidor, o marcador de arquitetura MVA e, para cada ferramenta, ações, flags destrutivas e somente leitura, campos obrigatórios e, para cada Presenter, chaves de esquema, tipos de bloco de UI suportados e indicação de regras contextuais. Diferentemente do cartão estático, o manifesto é lido pela conexão MCP, o que significa que é filtrado por sessão: o filtro recebe o manifesto e o contexto da requisição e retorna o que aquela sessão pode ver. A descoberta baseada em função é, portanto, uma função e não um endpoint separado.

Use o manifesto quando os agentes precisarem se orientar sozinhos: um agente pode ler mcpfusion://manifest.json primeiro e planejar com base na superfície exata à qual tem direito.

Metadados no processo

O registro responde a perguntas sobre a própria superfície sem uma ida e volta pelo wire:

typescript
for (const builder of registry.getBuilders()) {
  console.log(builder.getName(), builder.getActionNames());
  for (const action of builder.getActionMetadata()) {
    console.log(action.actionName, action.destructive, action.requiredFields);
    console.log(action.hasMiddleware, action.presenterName);
    console.log(action.presenterSchemaKeys, action.presenterUiBlockTypes);
  }
}

Este é o mesmo material consumido pelo compilador de contratos. Por isso a CLI pode imprimir sua superfície, o lockfile pode gerar um hash dela e um painel administrativo pode renderizá-la: uma fonte, três consumidores.

Contratos e digests

Cada ferramenta é materializada em um ToolContract com seções de superfície, comportamento, economia de tokens e permissões, cada uma com seu hash. computeServerDigest() as compõe em um digest do servidor; compareServerDigests() informa se duas implantações são comportamentalmente idênticas. O lockfile grava exatamente esse material em disco. Consulte Contracts para ver o esquema e a barreira de CI.

Por que isso importa na operação

  • Onboarding: um novo cliente lê o cartão e conhece o transporte e o endpoint antes de se conectar
  • Privilégio mínimo: o filtro do manifesto transforma a visibilidade de capacidades em uma decisão de runtime por função
  • Auditoria: o digest do contrato é o artefato assinado por um revisor, não uma captura de tela de um painel
  • Detecção de regressões: comparar digests entre releases responde "o comportamento mudou" sem ler um diff de todo o repositório

Próximos passos