Skip to main content

​
Métodos suportados

O servidor MCP aceita dois métodos de autenticação:
MétodoQuando usarIdentificação
OAuth 2.1 (PKCE)Clientes interativos: Claude, Cursor, ChatGPT, VS CodeLogin pelo navegador, tokens com expiração
API KeyAutomações, scripts, clientes sem suporte a OAuthToken estático com prefixo mak_
Os dois métodos passam pelo mesmo controle de permissões e escopos.

​
OAuth 2.1

O servidor implementa OAuth 2.1 com PKCE e Dynamic Client Registration (DCR), seguindo a especificação oficial de auth do MCP.

​
Endpoints

EndpointURL
Discoveryhttps://app.morada.ai/api/mcp/well-known/oauth-authorization-server
Authorizehttps://app.morada.ai/api/mcp/oauth/authorize
Tokenhttps://app.morada.ai/api/mcp/oauth/token
Dynamic Registrationhttps://app.morada.ai/api/mcp/oauth/register

​
Fluxo

1

Discovery

O cliente MCP busca o documento .well-known/oauth-authorization-server e descobre todos os endpoints e escopos suportados.
2

Dynamic Client Registration

Se o cliente ainda não tem um client_id, ele se registra automaticamente em /oauth/register e recebe um client_id público (sem client_secret — apenas PKCE).
3

Authorization

O cliente abre o navegador na URL de authorize com um code_challenge. O usuário faz login na Morada.ai e vê a tela de consentimento com os escopos solicitados.
4

Token exchange

Após aprovar, o cliente recebe um authorization_code, troca por um access_token (e refresh_token) em /oauth/token usando PKCE.
5

Uso

Toda chamada ao MCP envia Authorization: Bearer <access_token>. Quando o token expira, o cliente usa o refresh_token automaticamente.
Tokens OAuth carregam o conjunto de escopos aprovado pelo usuário. Mesmo que o usuário tenha permissão total na plataforma, o cliente só pode chamar tools cobertas pelos escopos concedidos.

​
API Key

API keys são úteis para automações ou clientes que não suportam OAuth.

​
Criando uma API key

1

Abra Configurações da Conta

Na plataforma, clique no seu avatar → Configurações da conta.
2

Localize MCP API Keys

Role até a seção MCP API Keys.
3

Gere uma nova chave

Informe um nome descritivo (ex.: automação-relatórios), escolha o nível de acesso e clique em Gerar.
NívelEscopos incluídos
Somente leituraconversations:view deals:view instances:view integrations:view dashboard:view message-templates:view
Acesso completoAcima + instances:edit integrations:edit talk:edit message-templates:edit
4

Copie a chave imediatamente

O token completo (mak_...) é exibido apenas uma vez. Guarde em local seguro.
Após fechar o diálogo, só o prefixo da chave fica visível. Se perder o token completo, será necessário revogar e gerar uma nova.

​
Usando a API key

Envie no header Authorization: 
curl https://app.morada.ai/api/mcp \
  -H "Authorization: Bearer mak_SUA_API_KEY" \
  -H "Content-Type: application/json"
Em clientes MCP, configure o header customizado: 
{
  "mcpServers": {
    "morada-platform": {
      "url": "https://app.morada.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer mak_SUA_API_KEY"
      }
    }
  }
}

​
Revogando uma API key

Na mesma tela de MCP API Keys, clique no ícone de lixeira ao lado da chave e confirme. A revogação é imediata.
A coluna Último uso ajuda a identificar chaves inativas que podem ser revogadas com segurança.

​
Escopos disponíveis

Cada escopo libera um conjunto de ferramentas. O usuário ainda precisa ter a permissão correspondente na plataforma para que a chamada seja autorizada.
EscopoFerramentas liberadas
conversations:viewlist_conversations, get_conversation, list_conversation_messages
deals:viewlist_deals, get_deal
instances:viewlist_agents, get_agent
integrations:viewlist_integrations, get_integration
dashboard:viewget_analytics
talk:editsend_active_message
message-templates:viewlist_message_templates
message-templates:editcreate_message_template
A ferramenta list_workspaces não exige escopo específico — todo token autenticado pode descobrir os workspaces do usuário.

​
Como a autorização é avaliada

Em toda chamada, o servidor verifica:
1

Token válido

O token (OAuth ou API key) existe, não expirou e está associado a um usuário ativo.
2

Escopo concedido

A ferramenta solicitada está coberta pelos escopos do token.
3

Permissão na plataforma

O usuário tem a permissão correspondente (ex.: Deals.View) no workspace alvo, herdada do seu papel.
4

Pertencimento ao workspace

Para tools que recebem workspaceId, o usuário precisa ter acesso àquele workspace específico.
Se qualquer uma das checagens falhar, a chamada retorna erro de autorização — independente da permissão dos demais escopos.

​
Próximos passos

Instalação

Conectar Claude, Cursor, ChatGPT e outros clientes.

Ferramentas

Catálogo completo de tools expostas pelo MCP.