Como oferecer um MCP dentro do seu produto

Cada usuário do seu app conecta a conta dele: connect sessions com client_ref, webhook de conexão, leitura por API e as páginas de conexão no seu domínio.

Needs your own key

Run with AI

Skip the reading: send this guide as a ready-to-run prompt. It tells the assistant to stop and ask you whenever it needs a credential or a step only you can do.

Claude Code opens with the prompt filled in but not sent, so you can review it first.

Seu produto já tem usuários, e cada um deles tem conta em algum sistema que você gostaria de ler: o ERP, o CRM, a plataforma de assinatura eletrônica, o e-mail. O que falta é o pedaço do meio — a tela onde a pessoa autoriza esse acesso, o armazenamento seguro da credencial dela e uma API pra ler os dados depois.

É isso que este guia monta, e vale pra qualquer MCP do catálogo: cada usuário do seu app conecta a conta dele, numa tela servida por nós, e os dados chegam amarrados ao id que você já usa pra identificar essa pessoa.

Os exemplos usam o ZapSign (assinatura eletrônica), mas troque o slug e o fluxo é idêntico para qualquer outro MCP — o mecanismo é da plataforma, não do conector.

Este guia é o oposto de instalar um MCP pra você mesmo. Lá você conecta as suas contas. Aqui quem conecta é o seu cliente, cada um a dele, dentro do seu produto.

Passo 0 — o que precisa antes

Conta em app.mcp.ai com o MCP que você quer oferecer já instalado (o exemplo aqui é o ZapSign).
Em Configurações → API keys, uma Workspace API key (sk_live_…).
O id da sua instalação (começa com mi_):

bash

curl -s https://app.mcp.ai/api/mcps \
  -H "Authorization: Bearer $MCPAI_KEY" \
  | grep -i zapsign

Guarde esse mi_…: ele aparece em todos os passos.

Passo 1 — gerar o link de conexão de um usuário

Pra cada usuário do seu app que for conectar a conta dele, você cria uma connect session. Ela devolve uma URL de uso único.

bash

curl -s -X POST https://api.mcp.ai/api/connect-sessions \
  -H "Authorization: Bearer $MCPAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "install_id": "mi_...",
    "client_ref": "user_8421",
    "redirect_uri": "https://seuapp.com/integracoes/conectado"
  }'

Resposta:

json

{
  "session": {
    "id": "cs_...",
    "install_id": "mi_...",
    "client_ref": "user_8421",
    "status": "pending",
    "expires_at": "2026-08-25T12:00:00.000Z"
  },
  "connect_url": "https://app.mcp.ai/connect/mi_...?u=usr_...&cs=cs_...&add_only=1"
}

O campo que faz o sistema funcionar é o client_ref: é o seu id de usuário, opaco pra nós. Ele volta no webhook quando a conexão nasce, e é assim que você sabe qual dos seus usuários acabou de conectar. Sem ele você recebe "uma conexão nova" sem saber de quem.

redirect_uri é opcional: com ele, o usuário volta pro seu app depois do fluxo; sem ele, tudo termina na nossa tela. Na volta a gente acrescenta três parâmetros na sua URL (preservando a query que você já tinha nela):

cs — o id da sessão;
client_ref — o seu id de usuário, de volta;
status — connected, error ou canceled. Só connected é sucesso. Não trate "o usuário voltou" como "conectou": quem desiste no meio ou esbarra num erro do banco também volta, com o status dizendo o quê. Nesses dois casos a sessão não é consumida — a mesma connect_url deixa tentar de novo.

O status da URL serve pra sua tela reagir na hora; a fonte de verdade da conexão continua sendo o webhook connection.created (passo 3) ou o GET da sessão. Precisa ser https (http só em localhost, pra desenvolver).

Passo 2 — o usuário conecta

Abra a connect_url pro seu usuário (redirect, ou um <iframe> se você tiver o plano com iframe liberado). Nessa tela ele autoriza o acesso no ambiente do próprio provedor e aceita o consentimento de leitura dos dados.

Duas coisas que valem entender agora, porque não são configuráveis:

A tela é nossa. É uma tela genérica de conexão, que ganha a sua marca quando você tem domínio próprio (veja "Sua marca no fluxo", abaixo). Você não constrói nem mantém esse fluxo — nem o consentimento, nem o tratamento de erro do provedor, nem a lista de contas.
O consentimento é obrigatório e não tem como pular. É o que autoriza a leitura, e é dele que sai o direito de você receber esses dados.

Passo 3 — saber que conectou

Duas formas. Prefira a primeira.

Webhook (recomendado). Configure uma vez, em PUT https://api.mcp.ai/api/installs/<mi_...>/webhook, assinando o evento connection.created. O passo a passo completo, com validação de assinatura, está no guia webhook de movimentação — a mecânica é a mesma, só muda o evento.

O corpo que chega:

json

{
  "event": "connection.created",
  "install_id": "mi_...",
  "mcp_slug": "zapsign",
  "workspace_id": "ws_...",
  "connection_id": "...",
  "client_ref": "user_8421",
  "total_connections": 12,
  "ts": "2026-08-25T11:32:04.881Z"
}

client_ref de volta + connection_id = o par que fecha o loop. Grave essa dupla na sua base: connection_id é como você vai pedir os dados daquele usuário depois.

Polling (alternativa). GET https://api.mcp.ai/api/connect-sessions/<cs_...> devolve a sessão com status e connection_id quando concluída. Serve pra confirmar uma conexão específica, mas não substitui o webhook — reconexões e conexões feitas depois não passam por essa sessão.

Passo 4 — ler os dados daquele usuário

Todo MCP ganha uma API REST em https://api.mcp.ai/api/<slug> — no exemplo, /api/zapsign. Para listar as conexões que existem no seu workspace:

bash

curl -s https://api.mcp.ai/api/zapsign/_accounts \
  -H "Authorization: Bearer $MCPAI_KEY"

E para ler os dados de um usuário, mande o account correspondente ao connection_id que você guardou no passo 3:

bash

curl -s -X POST https://api.mcp.ai/api/zapsign/documents/list \
  -H "Authorization: Bearer $MCPAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "..."}'

A lista completa de endpoints (com parâmetros e exemplos) é servida pelo próprio MCP, sem autenticação:

https://api.mcp.ai/api/zapsign/_endpoints — JSON estruturado
https://api.mcp.ai/api/zapsign/_openapi — OpenAPI 3.1, importável no Insomnia/Postman
https://api.mcp.ai/api/zapsign/_skill.md — versão em markdown, pra colar nas instruções de um agente de IA

Sua marca no fluxo (domínio próprio)

Com o plano Enterprise, as páginas de conexão passam a ser servidas num domínio seu, com o seu nome e o seu logo:

Na página do MCP em app.mcp.ai, abra a aba Configurações → Domínio próprio.
No campo Domínio de conexão, informe o domínio (ex.: conectar.seuapp.com) e crie o CNAME que a tela mostra.
Clique em Verificar. Quando estiver no ar, as connect_url geradas no Passo 1 já saem nesse domínio, automaticamente.

O que muda: o domínio, o nome, o logo e o link de suporte. O que não muda: a tela continua sendo a nossa tela de conexão, e o consentimento continua aparecendo. É o desenho certo — é ele que dá lastro jurídico à leitura dos dados.

E o segundo campo, "Domínio do endpoint MCP"? Ele existe pra um caso diferente do deste guia, e é opcional: serve quando os seus usuários finais plugam um MCP no próprio Claude/ChatGPT deles, pra conversar com os próprios dados. Se a sua integração é a deste guia (o seu backend consome a API REST), o endereço da API nunca aparece pro usuário final e esse campo não muda nada — pode deixar vazio. Se o seu caso for o outro, fala com a gente que a gente te manda o caminho.

Um cliente por chave (isolamento)

Se o seu caso é revenda (você administra contas de clientes distintos, tipo uma contabilidade), dá pra travar uma sk_live_ num MCP e numa conexão específica: quem tiver aquela chave só enxerga aquele cliente, e não consegue trocar de conexão nem listando.

Esse escopo ainda não está no formulário de criação de chave do painel — hoje a gente configura pra você. Escreva pra contato@mcp.ai com os connection_id que precisam ser isolados.

O que conta como uso

Cada MCP tem o próprio modelo de cobrança, e a página dele em app.mcp.ai mostra qual é. Dois padrões aparecem com frequência, e vale saber a diferença antes de desenhar o onboarding:

Por conexão — você paga por conta conectada. Nesses, uma contagem comum é por ciclo, e não pela foto do momento: se o usuário conectar e desconectar dentro do mesmo mês, aquela conexão já contou. Um fluxo que faz o usuário conectar "pra testar" e desconectar em seguida custa igual a um que ficou.
Por chamada / por crédito — você paga pelo que consome, e conectar é de graça.

Confira o modelo do seu MCP na aba de planos antes de projetar volume.

O que não dá

Fazer o que o MCP não faz. Cada conector expõe um conjunto fixo de ferramentas, e alguns são read-only por arquitetura. A lista real está em /_endpoints; se a operação não está lá, ela não existe.
Pular o consentimento. Nem por API, nem com domínio próprio. É ele que dá lastro à leitura dos dados do seu usuário.
Guardar a credencial do seu usuário. Você nunca vê a senha nem o token dele — quem detém a conexão somos nós, e você referencia por connection_id.

Próximo passo

Testar sem pagar: instale o MCP em app.mcp.ai, conecte uma conta sua e use a franquia gratuita dele. Serve pra ver o formato exato dos dados antes de escrever qualquer integração.

Quando for dimensionar volume ou quiser o domínio próprio, fale com a gente em contato@mcp.ai.

More guides

Needs your own key

Cada usuário do seu app com o MCP dele

Em vez de consumir a API no seu backend, cada usuário final pluga o MCP dele no Claude/ChatGPT: toolkit e convite por usuário, isolamento de fábrica e a URL no seu domínio.

Guides

Back to BTCPay Server