MCP Celcoin — Enterprise Banking Integration Server

Análise Comparativa

Execução Real vs. Busca em Documentação

O MCP da kapa.ai (celcoin-docs) é um proxy de documentação read-only. O MCP Celcoin é um servidor operacional que executa operações financeiras reais via API.

celcoin-docs (kapa.ai)

Hosted Documentation Search — HTTP Transport

1 única tool: busca semântica em docs
Read-only — não executa nenhuma operação
Sem autenticação com API Celcoin
Sem mTLS, sem OAuth2, sem tokens
Sem validação de schemas (Zod)
Sem confirm gates para operações financeiras
Sem mascaramento de PII
Zero testes — wrapper genérico
Rate limited: 40 req/hora ou 200 req/dia (público); 60 req/min (API key)
Depende da indexação do kapa.ai
Não possui gerenciamento de estado/tokens

MCP Celcoin (CSBFinTech)

Full Operational Server — stdio Transport

62 tools executáveis em 9 domínios
Executa operações reais: PIX, TED, boleto, credit
Dual auth: mTLS + OAuth2 (BaaS) e Basic Auth (Credit)
Token caching com mutex e TTL dinâmico
Zod runtime validation em todos os 62 handlers
31 confirm gates para operações financeiras
PII masking automático (CPF, CNPJ, email, conta)
295 testes, 86% coverage, 16 suites
Sem rate limiting externo
Fonte da verdade: código tipado, não indexação
Gerenciamento completo de estado e tokens

Critério	celcoin-docs (kapa.ai)	MCP Celcoin (CSBFinTech)
Tipo de Servidor	Proxy de documentação hospedado	Servidor operacional completo
Transporte MCP	HTTP (remoto, dependente de rede kapa.ai)	stdio (local, zero latência de rede)
Tools Disponíveis	1 (busca semântica) 1 tool	62 tools executáveis 62 tools
Executar PIX/TED/Boleto	Não — apenas retorna docs sobre PIX	Sim — executa com preview/confirm
Abertura de Conta	Não	Sim — PF/PJ com onboarding completo
Originação de Crédito	Não	Sim — 16 tools (pessoa, simulação, CCB, desembolso)
Autenticação mTLS	Não	Sim — cert + key + passphrase, rejectUnauthorized
Token Management	N/A	Promise-mutex + TTL dinâmico + buffer
Validação de Schema	Não	Zod safeParse em 62 handlers (advisory)
Proteção Financeira	N/A	31 confirm gates + amount bounds (max 999.999.999)
Mascaramento PII	Não	Automático — CPF, CNPJ, email, conta
Cobertura de Testes	N/A	295 testes — 86% stmt / 90% branch / 96% func
Docker	N/A — SaaS remoto	268 MB — multi-stage, 0 vulnerabilidades
Disponibilidade	Depende da infra kapa.ai + internet	Roda local ou on-premise, zero dependência externa
Custo Operacional	SaaS pago (kapa.ai) + rate limits	Self-hosted, sem custo de terceiros
Customização	Zero — black box	100% — open source, extensível
Evolução / Roadmap	Controlado pelo kapa.ai	Controlado por você — add tools, domínios, regras

Arquitetura

Camadas do Servidor MCP

Arquitetura em camadas isoladas com responsabilidades claras. Cada camada pode ser auditada, testada e substituída independentemente.

AI Agent

Claude, GPT, etc.

→

MCP Server

62 tools + 3 resources

→

Zod Validation

Input + Response

→

Auth Layer

mTLS + OAuth2 + Mutex

→

HTTP Client

BaaS + Credit

→

Celcoin API

BaaS & CaaS

Camada MCP (Protocolo)

Servidor MCP com SDK oficial da Anthropic. Registra 62 tools com schemas Zod tipados e 3 resources de referência. Transporte stdio para integração local zero-latência.

@modelcontextprotocol/sdk stdio transport Zod schemas

Camada de Autenticação

Dual auth: BaaS via mTLS (cert + key + passphrase) + OAuth2 client_credentials; Credit via Basic Auth (base64). Token caching com Promise-mutex, TTL dinâmico server-side com buffer de segurança.

mTLS OAuth2 Basic Auth Promise-mutex

Camada HTTP Client

Dois clientes isolados: baasClient (mTLS) e creditClient (Basic Auth). Interceptors para token injection automático, conversão centavos→reais no boundary, timeout e retry.

axios interceptors cents→float

Camada de Validação

Zod schemas validam inputs (bloqueante) e responses (advisory safeParse — logs sem bloquear). Garantem type-safety em runtime sem impactar disponibilidade.

Zod safeParse advisory mode

Camada de Segurança

20 findings remediados. PII masking automático em logs e respostas de erro. Confirm gates em 31 tools financeiras. Amount bounds (max R$ 9.999.999,99). URL encoding contra injection. rejectUnauthorized: true.

PII Masking Confirm Gates Amount Bounds URL Encoding

Camada de Error Handling

Normalização de 4 formatos de erro Celcoin para código MCP estruturado. 11 tipos de erro tipados. PII masking aplicado antes de qualquer output. Stack traces suprimidos em produção.

CelcoinError 11 error codes normalized output

Domínios

62 Tools em 9 Domínios Operacionais

Cada domínio cobre uma vertical da API Celcoin com operações completas de leitura e escrita.

PIX10 tools

QR codes dinâmicos/estáticos, cash-out, cash-in, reversal, decode EMV, participantes

BaaS Client

DICT Keys8 tools

Criar, listar, deletar chaves PIX. Portabilidade e reivindicação de chaves

BaaS Client

Transfers5 tools

TED, TEF, transferência interna. Status de transferência

BaaS Client

Billets4 tools

Emissão de boleto, status, cancelamento, download PDF

BaaS Client

Bill Payment3 tools

Autorização, pagamento e status de boletos de terceiros

BaaS Client

Onboarding10 tools

Abertura PF/PJ, consulta de propostas, atualização, fechamento de conta

BaaS Client

Credit (CaaS)16 tools

Produtos, pessoas, empresas, SCR, simulação, CCB, qualificação, desembolso

Credit Client

Webhooks3 tools

Criar, listar e deletar subscrições de webhook BaaS

BaaS Client

DDA2 tools

Registro DDA e listagem de webhook routes

BaaS Client

Balance1 tool

Consulta de saldo em centavos por conta

BaaS Client

Segurança

Hardening para Operações Financeiras

20 findings de segurança identificados e remediados. Cada camada implementa controles específicos para ambiente bancário regulado.

🔒

mTLS (Mutual TLS)

Autenticação mútua com certificado digital, chave privada e passphrase. rejectUnauthorized: true — zero tolerância a certificados inválidos.

Certificado carregado de env var ou arquivo
Agent HTTPS cacheado para performance
Suporte a inline cert e file path

🛡

Confirm Gates (Preview/Execute)

31 tools financeiras requerem confirm: true explícito. Sem confirmação, retornam preview da operação sem executar.

PIX: cash-out, QR codes, reversão
Transfers: TED, TEF, interna
Credit: CCB, desembolso, qualificação
Onboarding: abertura e fechamento de conta

👁

PII Masking

Mascaramento automático aplicado em todas as respostas de erro e logs. Dados sensíveis nunca vazam para o AI Agent.

CPF: 123.456.789-00 → ***.***789-**
CNPJ: 12.345.678/0001-00 → **.***.678/****-**
Email: user@domain → u***@domain
Conta: 12345678 → *****678

💰

Amount Bounds

Todos os campos monetários limitados a max: 999.999.999 centavos (R$ 9.999.999,99). Previne overflow e erros de magnitude.

Validação Zod no input (bloqueante)
Conversão centavos→reais na camada client
Inteiro na interface MCP, float na API

🔐

Token Security

Promise-based mutex previne token races. TTL dinâmico do servidor com buffer de segurança de 60s (BaaS) e 300s (Credit).

Token nunca exposto em logs
Refresh automático transparente
Um único refresh por janela (mutex)

🛠

Error Normalization

4 formatos de erro Celcoin normalizados para 11 códigos estruturados. PII masking aplicado antes de qualquer output ao agent.

Stack traces suprimidos (produção)
Erros tipados: CelcoinErrorCode
Detalhes preservados para debug

📋 Checklist de Auditoria Técnica

✓

mTLS com rejectUnauthorized: trueCertificados inválidos são rejeitados — zero man-in-the-middle

✓

Credenciais via Environment VariablesNenhum secret hardcoded — suporte a env vars e arquivo

✓

PII Masking em todas as saídas de erroCPF, CNPJ, email, número de conta mascarados automaticamente

✓

Confirm gates em 31 tools financeirasPreview obrigatório antes de execução — previne execuções acidentais

✓

Amount upper bound: R$ 9.999.999,99Proteção contra overflow e erros de magnitude em operações financeiras

✓

URL Encoding em path parametersPrevine injection via parâmetros de URL

✓

Token mutex (Promise-based)Previne race conditions em refresh concorrente de tokens

✓

Zod runtime validation (advisory)62 handlers com safeParse — detecta drift sem bloquear

✓

Docker 0 vulnerabilidadesMulti-stage build, node:22-alpine, 268 MB, scan limpo

✓

CI/CD com build + lint + testGitHub Actions pipeline automatizado em cada push

✓

Logging exclusivo via stderrstdout reservado para protocolo MCP — logs nunca poluem o canal

✓

295 testes automatizadosAuth, client, tools, error handling — 86% stmt, 90% branch, 96% func

Valor Estratégico

Diferenciais de Negócio

Além da superioridade técnica, o MCP Celcoin entrega valor tangível para operação, compliance e evolução.

⚙

Automação de Operações Financeiras

Agentes AI podem abrir contas, emitir boletos, transferir via PIX/TED, originar crédito — tudo via linguagem natural com confirmação explícita. O kapa.ai apenas explica como fazer.

📊

Compliance por Design

PII masking, confirm gates, amount bounds e audit trail atendem requisitos regulatórios (BACEN, LGPD). O MCP docs não tem nenhuma camada de compliance.

🚀

Time-to-Market

Integrar um novo agente com 62 operações bancárias leva minutos, não semanas. Schema tipado, autenticação pronta, error handling completo.

🔑

Soberania e Controle

Roda local ou on-premise. Sem dependência de SaaS terceiro. Sem rate limits externos. Sem vendor lock-in. Todo o código é auditável.

🔎

Observabilidade

Logs estruturados via stderr, erros tipados com códigos MCP, Zod warnings para API drift detection. Rastreabilidade completa de cada operação.

🛠

Extensibilidade

Adicionar novos domínios (Bill Payments avançados, Compliance, Relatórios) é registrar novas tools no mesmo padrão. Arquitetura modular facilita contribuições.

      
        Exemplo: Agent AI executando PIX via MCP
    
// O agente AI chama a tool MCP com linguagem natural processada
// Passo 1: Preview (confirm: false) — nenhuma operação executada
celcoin_pix_cashout({
  amount: 15000,             // R$ 150,00 em centavos
  clientCode: "PIX-2026-001",
  debitPartyAccount: "123456",
  debitPartyDocumentNumber: "12345678900",
  initializationType: "DICT",
  creditPartyKey: "email@destino.com",
  confirm: false          // ← Preview only
})

// Passo 2: Agent mostra preview ao usuário e pede confirmação
// Passo 3: Execução (confirm: true) — operação irreversível
celcoin_pix_cashout({ ..., confirm: true })
// → PIX executado, PII mascarada na resposta

Evolução

Roadmap de Evolução

O MCP Celcoin é um produto vivo com roadmap controlado pela equipe. O kapa.ai docs é estático e depende da indexação de terceiros.

Fase 1 — Completa

Core Infrastructure

Dual auth (mTLS + OAuth2), HTTP clients, error handler, PII masking, token caching com mutex.

Fase 2 — Completa

62 MCP Tools em 9 Domínios

PIX, DICT, Transfers, Billets, Bill Payment, Onboarding, Credit, Webhooks, DDA. Confirm gates em 31 tools.

Fase 3 — Completa

Quality & Security Hardening

295 testes, 20 security findings remediados, Zod advisory validation, Docker 0 vulns, CI/CD.

Fase 4 — Em Andamento

Sandbox Testing & Publication

Testes com API sandbox real da Celcoin. npm publish. Registro no MCP Registry oficial.

Fase 5 — Planejada

Domínios Avançados

Bill Payments avançados, Compliance/KYC, Relatórios, Extrato, Câmbio digital, Open Finance.

Fase 6 — Planejada

Enterprise Features

Multi-tenant, rate limiting configurável, audit log persistente, metrics/Prometheus, SSE transport.

Setup

Instalação em 2 Minutos

      
        claude_desktop_config.json
    
{
  "mcpServers": {
    "celcoin": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/mcp-celcoin",
      "env": {
        "CELCOIN_API_URL":            "https://sandbox.openfinance.celcoin.dev",
        "CELCOIN_CLIENT_ID":           "your-client-id",
        "CELCOIN_CLIENT_SECRET":       "your-client-secret",
        "CELCOIN_CERT_PATH":           "/path/to/cert.pem",
        "CELCOIN_CERT_KEY_PATH":       "/path/to/key.pem",
        "CELCOIN_CERT_PASSPHRASE":     "your-passphrase",
        "CELCOIN_CREDIT_API_URL":      "https://sandbox.openfinance.celcoin.dev",
        "CELCOIN_CREDIT_CLIENT_ID":    "your-credit-id",
        "CELCOIN_CREDIT_CLIENT_SECRET": "your-credit-secret"
      }
    }
  }
}

💡

      Comparação de setup: O kapa.ai docs requer claude mcp add --transport http celcoin-docs https://celcoin.mcp.kapa.ai
      e te dá 1 tool read-only. O MCP Celcoin te dá 62 tools executáveis com autenticação, segurança e validação — pronto para operações financeiras reais.
    

MCP Celcoin Enterprise BankingIntegration Server

Execução Real vs. Busca em Documentação

celcoin-docs (kapa.ai)

MCP Celcoin (CSBFinTech)

Camadas do Servidor MCP

Camada MCP (Protocolo)

Camada de Autenticação

Camada HTTP Client

Camada de Validação

Camada de Segurança

Camada de Error Handling

62 Tools em 9 Domínios Operacionais

Hardening para Operações Financeiras

mTLS (Mutual TLS)

Confirm Gates (Preview/Execute)

PII Masking

Amount Bounds

Token Security

Error Normalization

📋 Checklist de Auditoria Técnica

Cobertura de Testes

Diferenciais de Negócio

Automação de Operações Financeiras

Compliance por Design

Time-to-Market

Soberania e Controle

Observabilidade

Extensibilidade

Roadmap de Evolução

Core Infrastructure

62 MCP Tools em 9 Domínios

Quality & Security Hardening

Sandbox Testing & Publication

Domínios Avançados

Enterprise Features

Instalação em 2 Minutos

MCP Celcoin
Enterprise Banking
Integration Server