Pular para o conteúdo
thiagoetipadrões

Contatos

apps/api/mcp-server

123 · API & Integração · ≈ 6 min de estudo

MCP Server

Expõe capacidades do backend a agentes de IA pelo Model Context Protocol: o agente descobre as ferramentas, lê o schema de entrada de cada uma e as chama por JSON-RPC em POST /mcp. O servidor MCP é só mais uma superfície sobre os mesmos use cases da API REST — mesmo schema, mesma regra, mesma mensagem de recusa. Use quando um assistente precisa consultar e simular operações do sistema com as regras que já valem para o resto.

passos
6
arquivos
4
testes
0
tecnologias
6
Infraestrutura realTypeScriptBunElysiaPostgreSQLMCP SDKDocker
CenárioRelaçõesComparar
Baixar cartão

Cenário

O banco digital oferece um assistente que responde saldo, extrato e se uma transferência passaria, e pode sugerir uma transferência. O assistente nunca movimenta dinheiro: ele registra uma proposta que o titular aprova no app. As regras — saldo e limite diário considerando os débitos de hoje — são as mesmas que a API REST aplica, escritas uma vez só.

Planta

Sequência
10/10
POST /mcp tools/list1account_balance, account_statement, transfer_simulate, transfer_propose2POST /mcp tools/call transfer_simulate3mesmo use case da rota REST4saldo e debitos de hoje5resultado, ou isError com o motivo6tools/call transfer_propose7proposta pendente, nada se move8POST /transfers/proposals/:id/approve (REST, fora do MCP)9revalida sob lock, debita e credita10Agente de IA (cliente MCP)Backend ElysiaUse casesPostgreSQLTitular (app do banco)
10

10 passos — reproduza para seguir o fluxo

Como funciona

6 passos

Expõe ferramentas a agentes de IA.

Esconde cada passo: lembre antes de tocar para revelar.

  1. 01

    Os schemas TypeBox de entrada são declarados uma vez: o Elysia valida os corpos REST com eles e o MCP os publica como inputSchema (fromJsonSchema), sem conversor

  2. 02

    createMcpHandler (SDK oficial v2) atende POST /mcp sem sessão: um McpServer novo por requisição

  3. 03

    Argumento fora do schema volta como isError antes de tocar o domínio; recusa de negócio (ErrorBusiness) também volta como isError, com a mesma mensagem que a REST devolve em 422

  4. 04

    As ferramentas só leem, simulam e propõem; aprovar é rota REST do titular, não ferramenta do agente

  5. 05

    A aprovação trava as duas contas em ordem, revalida saldo e limite e só então move o dinheiro; aprovar de novo é recusado

  6. 06

    Números inteiros publicados como number com multipleOf: 1, porque t.Integer do Elysia publicaria um anyOf com ramo string

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

  • O agente usa as regras reais do backend, sem cópia

  • Sem sessão: escala como qualquer rota HTTP

  • isError com motivo claro deixa o modelo se corrigir

  • Proposta mais aprovação mantém a pessoa no controle

Custos

  • Mais uma superfície pública para proteger e versionar

  • Cada chamada carrega o próprio contexto

  • Mensagem vaga vira nova chamada errada

  • Uma etapa a mais para o usuário concluir a operação

apps/api/mcp-server

4 arquivos

src/

  • use_case_account.tsSchemas únicos e use cases: saldo, extrato, simulação e proposta
  • use_case_approval.tsAprovação humana: o único caminho que move dinheiro
  • server_bank.tsRotas REST e POST /mcp com as ferramentas registradas

sql/

  • 01_schema.sqlschemaContas, transações e propostas

Executar · com Docker

  1. ./docker.sh up# sobe PostgreSQL
  2. cp .env.example .env# variáveis de ambiente
  3. bun install# dependências
  4. bun run demo# roda o cenário
  5. bun run test# integração contra o serviço real
Requisitos
BunDocker
Sobe junto
PostgreSQL

Relações

Onde ele se encaixa

Mapa
  1. MCP Server
  • Combina com3

Por que se relacionam

Combina com

Teste rápido

Qual destes combina com MCP Server?

Próximo projeto · Observabilidade & OperaçõesDistributed Tracing
Esc

↑ ↓ navegarEnter abrir191 resultados