Autenticação

Métodos suportados

O servidor MCP aceita dois métodos de autenticação:

Método	Quando usar	Identificação
OAuth 2.1 (PKCE)	Clientes interativos: Claude, Cursor, ChatGPT, VS Code	Login pelo navegador, tokens com expiração
API Key	Automações, scripts, clientes sem suporte a OAuth	Token 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

Endpoint	URL
Discovery	`https://app.morada.ai/api/mcp/well-known/oauth-authorization-server`
Authorize	`https://app.morada.ai/api/mcp/oauth/authorize`
Token	`https://app.morada.ai/api/mcp/oauth/token`
Dynamic Registration	`https://app.morada.ai/api/mcp/oauth/register`

Fluxo

Discovery

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

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).

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.

Token exchange

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

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

Abra Configurações da Conta

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

Localize MCP API Keys

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

Gere uma nova chave

Informe um nome descritivo (ex.: automação-relatórios), escolha o nível de acesso e clique em Gerar.

Nível	Escopos incluídos
Somente leitura	`conversations:view` `deals:view` `instances:view` `integrations:view` `dashboard:view` `message-templates:view`
Acesso completo	Acima + `instances:edit` `integrations:edit` `talk:edit` `message-templates:edit`

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.

Escopo	Ferramentas liberadas
`conversations:view`	`list_conversations`, `get_conversation`, `list_conversation_messages`
`deals:view`	`list_deals`, `get_deal`
`instances:view`	`list_agents`, `get_agent`
`integrations:view`	`list_integrations`, `get_integration`
`dashboard:view`	`get_analytics`
`talk:edit`	`send_active_message`
`message-templates:view`	`list_message_templates`
`message-templates:edit`	`create_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:

Token válido

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

Escopo concedido

A ferramenta solicitada está coberta pelos escopos do token.

Permissão na plataforma

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

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.

MCP da Morada.ai

Métodos suportados

OAuth 2.1

Endpoints

Fluxo

API Key

Criando uma API key

Usando a API key

Revogando uma API key

Escopos disponíveis

Como a autorização é avaliada

Próximos passos

Instalação

Ferramentas

​Métodos suportados

​OAuth 2.1

​Endpoints

​Fluxo

​API Key

​Criando uma API key

​Usando a API key

​Revogando uma API key

​Escopos disponíveis

​Como a autorização é avaliada

​Próximos passos

Instalação

Ferramentas

Métodos suportados

OAuth 2.1

Endpoints

Fluxo

API Key

Criando uma API key

Usando a API key

Revogando uma API key

Escopos disponíveis

Como a autorização é avaliada

Próximos passos