mcp.ai
ExploreHow it worksFAQ
  1. SSLMate Cert Spotter API
  2. /
  3. Guides

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

  1. Conta em app.mcp.ai com o MCP que você quer oferecer já instalado (o exemplo aqui é o ZapSign).
  2. Em Configurações → API keys, uma Workspace API key (sk_live_…).
  3. 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:

  1. Na página do MCP em app.mcp.ai, abra a aba Configurações → Domínio próprio.
  2. No campo Domínio de conexão, informe o domínio (ex.: conectar.seuapp.com) e crie o CNAME que a tela mostra.
  3. 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.

Try it with SSLMate Cert Spotter API

Connect the MCP and run the prompts from this guide.

Get started

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 SSLMate Cert Spotter API
mcp.ai

The registry and toolkit for Model Context Protocol servers. One link, every connector.

Explore

  • MCP Servers

Stay updated

The latest MCP servers and product updates, monthly.

© 2026 · mcp.ai, All rights reserved.
PrivacyTermsInvestors & partnershipsllms.txt