Copiar para IA

Servidor MCP (Model Context Protocol)

O padrão aberto para fornecer ferramentas financeiras à inteligência artificial agêntica.

O que é MCP?

O Model Context Protocol (MCP) é um padrão universal que permite que assistentes de inteligência artificial se conectem a fontes de dados seguras.

Ao configurar o Servidor MCP do Cord, você capacita agentes como o Claude ou assistentes integrados a IDEs (como o Cursor) a interagir de forma natural com a sua empresa.

Perguntas que você pode fazer à IA depois de conectada:

• “Extraia do PDF anexo os requisitos e gere um orçamento no Cord para este cliente.”
• “Revise os orçamentos vencidos dos últimos 30 dias e redija para mim e-mails de cobrança cordiais.”
• “Busque o cliente Distribuidora El Zarco e monte um rascunho com estes 3 itens.”

Como configurar a conexão

A autenticação do seu cliente de IA é feita com a sua chave de API padrão do Cord (sk_live_… / sk_test_…) — a mesma que a API REST usa.

1. Acesse Configurações › MCP na interface do Cord. Fica na seção Desenvolvedores do índice de Configurações, que aparece ao ativar o Modo desenvolvedor em Sua conta › Preferências.
2. Um painel de status no topo informa se você já tem uma chave ativa e, se já conectou um cliente de IA, quando ela foi usada pela última vez. Se você não tiver nenhuma, o botão “Criar chave para o MCP” gera uma chave de escrita com os grupos de leitura e de escrita de rascunhos, sem sair da página — ela é colada automaticamente na configuração abaixo. Copie-a nesse momento: ela não é exibida de novo. Para escolher grupos ou ferramentas avulsas, ou para permitir as ações com efeitos externos, crie ou edite a chave na aba Chaves do Cord Workbench (veja permissões por ferramenta).
3. Copie a configuração JSON do cliente MCP exibida na tela.
4. Cole essa configuração no caminho local correspondente ao seu cliente (por exemplo, o arquivo claude_desktop_config.json se você usa o aplicativo Claude for Desktop).

Duas formas de se conectar

Streamable HTTP (recomendado) — POST https://cordhq.app/api/mcp com o header Authorization: Bearer sk_live_…. Sem sessão: cada mensagem JSON-RPC é uma requisição HTTP independente. É o que a maioria dos clientes MCP modernos espera.

HTTP + SSE (legado, mantido para clientes antigos) — GET https://cordhq.app/api/mcp/sse abre uma conexão de longa duração e devolve para onde enviar as mensagens (POST /api/mcp/message?sessionId=…). Cada mensagem POST deve levar o mesmo Authorization: Bearer com que você abriu a sessão — o sessionId da URL não basta (ele viaja em texto simples e pode ficar exposto em logs de proxies intermediários), e a chave deve pertencer à mesma organização que abriu a sessão.

Permissões por ferramenta

Cada ferramenta pertence a um grupo e a um recurso, com o mesmo modelo das chaves restritas:

Grupo	Ferramentas	Chave sem lista
Leitura	listar_cotizaciones, detalle_cotizacion, cartera_vencida, resumen_negocio, buscar_cliente, listar_productos, listar_facturas, detalle_factura, listar_workflows_manuales, listar_eventos, estado_configuracion, validar_datos_fiscales, validar_apariencia	Permitidas
Escrita de rascunhos	crear_cotizacion_borrador, crear_factura_borrador, crear_cliente, crear_tarea, registrar_promesa_pago, proponer_configuracion	Permitidas com uma chave de escrita
Ações com efeitos externos	enviar_cotizacion, aprobar_cotizacion, rechazar_cotizacion, registrar_pago_cotizacion, actualizar_cliente, correr_workflow, simular_evento	Bloqueadas: só com permissão explícita, e cada chamada espera aprovação

Ao criar ou editar uma chave na aba Chaves do Workbench, você escolhe grupos inteiros ou, dentro de um grupo, ferramentas avulsas. Um grupo também cobre as ferramentas que o Cord adicionar depois; uma ferramenta avulsa, só ela. Uma chave sem lista, como todas as que existiam antes das permissões por ferramenta, mantém leitura e rascunhos conforme o seu nível e não pode pedir nenhuma ação com efeitos externos até que alguém a permita.

• O nível continua valendo: uma chave somente leitura não usa rascunhos mesmo que estejam na lista, e uma chave restrita (rk_) aplica o nível de cada recurso a cada ferramenta (listar_facturas pede facturas: read; crear_cotizacion_borrador, cotizaciones: write).
• tools/list só devolve o que a chave pode chamar. Se um cliente chamar outra, a resposta é um erro de ferramenta que diz qual falta e onde permiti-la.
• contexto_cuenta e buscar_documentacion estão sempre disponíveis: identificam a conta e buscam nesta documentação, sem dados de clientes.

actualizar_cliente está entre as ações com efeitos externos mesmo sem escrever para ninguém: o Cord usa o e-mail e os dados fiscais do cliente para enviar lembretes, faturas recorrentes e cobrança sem outra revisão, então alterá-los tem efeito fora do Cord.

Ações que esperam aprovação

Uma ação com efeitos externos não é executada quando o agente a chama, mesmo que a chave a permita e o cliente MCP não peça confirmação. O Cord guarda uma solicitação e responde:

{
  "estado": "pendiente_de_aprobacion",
  "aprobacion_id": "7c1e4b2a-5d3f-4a8e-9b6c-2f1d0e3a4b5c",
  "aprobacion_url": "https://cordhq.app/app/ajustes/mcp/solicitudes?modo=vivo#sol-7c1e4b2a-5d3f-4a8e-9b6c-2f1d0e3a4b5c",
  "vence": "2026-10-18T16:04:00.000Z",
  "mensaje": "No se ejecutó todavía: una persona con acceso a Cord tiene que aprobarla. …"
}

1. O agente compartilha aprobacion_url com o usuário.
2. Em Configurações › MCP › Solicitações, uma pessoa com permissão de Configurações e com a permissão da ação no app (Orçamentos para enviar ou registrar um pagamento, Aprovações para aprovar ou recusar, Clientes para atualizar um cliente, Orçamentos ou Cobrança para um workflow conforme o objeto, Configurações para simular um webhook) vê o documento, o que mudaria e os dados que o agente enviou, e aprova ou recusa.
3. Ao aprovar, o Cord executa a ação uma única vez, com o mesmo manipulador de sempre. Duas pessoas aprovando ao mesmo tempo não a executam duas vezes. Recusar não executa nada.
4. Para saber o resultado, o agente repete a chamada com a mesma idempotency_key: a resposta traz estado ejecutada (com o que a ação devolveu em resultado), fallida (com o motivo em error), rechazada ou vencida.

A solicitação vence em 72 horas sem decisão. Repetir a mesma chamada com os mesmos argumentos devolve a solicitação pendente em vez de criar outra, e uma organização recebe no máximo 30 solicitações por hora. Se a chave for revogada, vencer ou perder a ferramenta antes da decisão, a solicitação não pode mais ser aprovada. Com uma chave de teste, a solicitação fica no ambiente de teste e o link indica isso com ?modo=prueba.

Ferramentas disponíveis

Ferramenta	O que faz	Permissão
listar_cotizaciones	Lista orçamentos, com filtro opcional por status.	leitura
detalle_cotizacion	Detalhe completo de um orçamento: itens, totais, linha do tempo.	leitura
cartera_vencida	Contas a receber VENCIDAS: valor, aging, detalhe por cliente.	leitura
resumen_negocio	KPIs, funil de conversão, previsão do pipeline, uso do plano.	leitura
buscar_cliente	Busca no cadastro por empresa/contato/RFC/e-mail. Cada cliente traz language, o idioma dos documentos dele (null = o da organização). Paginada.	leitura
listar_productos	Catálogo de produtos (id, SKU, nome, unidade, preço de tabela). Paginada.	leitura
crear_cotizacion_borrador	Cria um orçamento em RASCUNHO (não o envia). Idempotente se você enviar idempotency_key.	rascunhos
listar_facturas	Lista as faturas do Cord Invoicing com o saldo e o status (draft|open|paid|void|uncollectible|overdue). Filtra por status, cliente ou texto livre. Paginada.	leitura
detalle_factura	Detalhe completo de UMA fatura: itens, emissor, destinatário, impostos, taxa de câmbio declarada, saldo e pagamentos recebidos.	leitura
crear_factura_borrador	Cria uma fatura em RASCUNHO para um cliente, sem precisar de um orçamento prévio. Disponível em todos os planos, incluindo o Grátis.	rascunhos
enviar_cotizacion	Pede para enviar ao cliente um orçamento em rascunho (e-mail com o link), no idioma dos documentos do cliente. Espera aprovação. No plano Grátis, consome um envio do mês.	com aprovação
aprobar_cotizacion	Pede para marcar como aprovado um orçamento enviado ou visualizado. Espera aprovação.	com aprovação
rechazar_cotizacion	Pede para marcar como recusado um orçamento enviado ou visualizado. Espera aprovação.	com aprovação
registrar_pago_cotizacion	Pede para registrar que um orçamento aprovado foi pago fora do Cord; ao ser executada, cancela as cobranças online pendentes dele. Aceita metodo_pago. Espera aprovação.	com aprovação
crear_cliente	Cadastra um cliente (empresa, contato, e-mail, telefone, identificação fiscal, condições, país e idioma dos documentos: es, en, pt, fr, de ou null).	rascunhos
actualizar_cliente	Pede para alterar os dados de contato de um cliente, inclusive language. Só modifica o que você envia; nunca toca crédito, nível nem desconto. O que já foi enviado mantém o idioma. Espera aprovação.	com aprovação
crear_tarea	Cria uma tarefa de acompanhamento: titulo (obrigatório), fecha limite YYYY-MM-DD, cotizacion_id e factura_id opcionais. Nasce sem responsável e com prioridade normal; isso se altera no app.	rascunhos
registrar_promesa_pago	Registra a data em que o cliente prometeu pagar um orçamento. Não cobra nada.	rascunhos
listar_workflows_manuales	Lista os workflows ativos “Você executa”, por objeto (quote ou invoice).	leitura
correr_workflow	Pede para executar um workflow “Você executa” em até 50 orçamentos ou faturas, com a versão publicada e as regras dele. Espera aprovação; ao ser executada, informa quantas execuções começaram.	com aprovação
listar_eventos	Histórico da empresa (orçamentos, faturas, clientes, tarefas, promessas), filtrável por tipo ou objeto. Paginada.	leitura
contexto_cuenta	Empresa, país, moeda, idioma, fuso horário, plano e se a chave é de teste ou de produção. Use-a primeiro.	leitura
proponer_configuracion	Propõe perfil, marca, impostos, catálogo e modelos a partir do site, de uma descrição ou da tabela de preços (base64, até 3 MB). Não aplica nada: devolve review_url para que uma pessoa a aprove.	rascunhos
estado_configuracion	Status de uma proposta (propuesto, aplicado, descartado, fallido) e o resultado por seção.	leitura
validar_datos_fiscales	Valida RFC, regime, uso do CFDI e código postal (México), NIF/NIE/CIF (Espanha) ou EIN (EUA) com as mesmas regras usadas ao emitir.	leitura
validar_apariencia	Valida um objeto appearance do Elements e informa quais chaves o Cord descartaria.	leitura
simular_evento	Pede para disparar um webhook de teste pelo motor real de entrega. Só com chave de teste. Espera aprovação.	com aprovação
buscar_documentacion	Busca nesta documentação e devolve as páginas mais relevantes com trecho e URL.	leitura

Cada ferramenta declara as anotações padrão do MCP (readOnlyHint, idempotentHint, destructiveHint) em tools/list. As de leitura são readOnlyHint: true e as que alteram o status de um orçamento são destructiveHint: true. A confirmação não depende de o cliente MCP respeitar essas anotações: o Cord não executa nenhuma ação com efeitos externos até que uma pessoa a aprove (veja ações que esperam aprovação). Nenhuma ferramenta emite nem carimba faturas: isso continua sendo uma ação que uma pessoa dispara pelo app ou pela API.

Nenhuma ferramenta altera as configurações da conta diretamente: proponer_configuracion deixa uma proposta que uma pessoa com permissão de Configurações revisa e aprova no Cord, assim como a que o onboarding ou o cord setup geram.

Toda ferramenta declara outputSchema e responde com structuredContent (o JSON validável) além do texto. Os valores viajam com a sua moeda em moneda: nunca presuma pesos.

Paginação

listar_cotizaciones, buscar_cliente, listar_productos, listar_facturas e listar_eventos devolvem páginas, não a tabela inteira. Há dois formatos de resposta.

buscar_cliente e listar_productos devolvem a lista em items, com total, has_more, next_cursor e a moeda em moneda; listar_cotizaciones devolve total, has_more e next_cursor com a lista em cotizaciones, e a moeda vai em cada orçamento:

{
  "items": [ { "id": "9a1c3e5f-7b2d-4f6a-8c0e-1d3b5f7a9c2e", "empresa": "Distribuidora El Zarco" } ],
  "total": 47,
  "moneda": "MXN",
  "has_more": true,
  "next_cursor": "20"
}

listar_facturas e listar_eventos devolvem só a lista (em facturas ou eventos) e next_cursor, sem total nem has_more:

{
  "eventos": [ { "id": "6b0e2f4a-8c1d-4e3b-9a5f-7d2c0e8b1a46", "type": "quote.approved" } ],
  "next_cursor": "MjAyNi0wOS0xNFQxODozMjowNC4xMjMwMDBafDZiMGUyZjRhLThjMWQtNGUzYi05YTVmLTdkMmMwZThiMWE0Ng"
}

Em todos os casos, chame de novo a mesma ferramenta passando cursor: next_cursor para a página seguinte. next_cursor vem como null quando não há mais resultados.

Chamadas seguras de repetir (idempotência)

crear_cotizacion_borrador, crear_cliente, crear_tarea, registrar_promesa_pago e as sete ações com efeitos externos aceitam um idempotency_key opcional — um identificador único que você gera (um UUID, por exemplo). Se o seu cliente MCP precisar repetir a chamada porque não recebeu resposta a tempo (timeout de rede), repita o MESMO idempotency_key: o Cord devolve o resultado da primeira vez em vez de repetir a ação. Em uma ação com efeitos externos, a mesma chave devolve o estado atual da solicitação (pendente, executada, recusada…). Reutilizar a mesma chave com outros argumentos devolve um erro, e nas demais ferramentas a chave expira em 24 horas.

{
  "name": "crear_cotizacion_borrador",
  "arguments": {
    "idempotency_key": "a1b2c3d4-…",
    "cliente_id": "9a1c3e5f-7b2d-4f6a-8c0e-1d3b5f7a9c2e",
    "items": [{ "descripcion": "Installation", "cantidad": 1, "precio_unitario": 4500 }]
  }
}

Sem idempotency_key, a ferramenta continua funcionando normalmente — cada chamada cria um novo rascunho (não é um campo obrigatório, apenas recomendado se o seu cliente repete as chamadas automaticamente).

Ferramentas seguras (Tools)

O Cord expõe de forma controlada “Ferramentas” (Tools) para a IA. Isso significa que a IA não tem acesso bruto e ilimitado ao seu banco de dados; a IA só pode invocar os endpoints que o Cord aprovou e categorizou, herdando as permissões vinculadas à chave de API.

Limites, medição e atividade

Cada chamada real (não as notificações de protocolo como notifications/initialized) conta como uma chamada à API REST na cota de uso do seu plano. Toda requisição HTTP ao servidor MCP, incluindo as notificações, entra nos limites por minuto da API (600 por chave secreta e 120 por IP de origem), e as ferramentas que alteram o status de um orçamento também compartilham o limite de 120 por minuto por organização; veja a tabela de limites. Cada chamada fica na aba Logs do Cord Workbench com a ferramenta que foi chamada (p. ex. /mcp/tools/call:listar_productos) — assim você vê exatamente o que o seu agente está fazendo, com qual chave e quando. Você pode filtrar esse log por método ou por status, ou buscar mcp na rota para isolar só o que a IA fez.

As ações com efeitos externos deixam rastro completo: cada chamada aparece em Logs com a chave que a fez, a decisão aparece em Configurações › Auditoria com a pessoa que aprovou ou recusou, e a ação executada é auditada como feita por essa chave.