Agentes IA · Servidor MCP

Instalação e Configuração

Não precisas de instalar nada no teu projeto nem de clonar repositórios. O servidor corre sob demanda via npx, e a única coisa que configuras é o teu cliente de IA.

1. Gerar o Personal Access Token

Entra no Portal do Desenvolvedor, abre Personal Access Tokens e cria um token novo. Copia-o de imediato — como qualquer token, só é mostrado uma vez.

O PAT dá acesso direto à tua conta de developer, incluindo às tuas apps Live. Guarda-o como guardarias uma password: nunca em código versionado, nunca partilhado em chat, e apenas em clientes de IA em que confias.

2. Variáveis de ambiente

Variável	Obrigatória	Descrição
`ACAPADEV_API_KEY`	Sim	O teu Personal Access Token. Sem ele, o servidor recusa arrancar.
`ACAPADEV_API_URL`	Não	URL base da API. Por omissão `https://api.acapadev.com`, que é o valor correto para toda a gente — só o alteres se a nossa equipa te indicar outro.
`ACAPADEV_ENV`	Não	`test` ou `live`. Define o ambiente assumido quando o assistente não indica um. Por omissão `test` — deixa assim salvo boa razão em contrário.

3. Configurar o cliente

Claude Code

A partir da raiz do teu projeto:

claude mcp add acapadev \
  --env ACAPADEV_API_KEY=O_TEU_TOKEN_AQUI \
  --env ACAPADEV_API_URL=https://api.acapadev.com \
  --env ACAPADEV_ENV=test \
  -- npx -y @devkussema/acapadev-mcp

Claude Desktop

Edita o claude_desktop_config.json:

{
  "mcpServers": {
    "acapadev": {
      "command": "npx",
      "args": ["-y", "@devkussema/acapadev-mcp"],
      "env": {
        "ACAPADEV_API_KEY": "O_TEU_TOKEN_AQUI",
        "ACAPADEV_API_URL": "https://api.acapadev.com",
        "ACAPADEV_ENV": "test"
      }
    }
  }
}

Cursor, Windsurf e Antigravity

Abre Settings → MCP Servers → Add New e usa a mesma estrutura:

{
  "mcpServers": {
    "acapadev": {
      "command": "npx",
      "args": ["-y", "@devkussema/acapadev-mcp"],
      "env": {
        "ACAPADEV_API_KEY": "O_TEU_TOKEN_AQUI",
        "ACAPADEV_API_URL": "https://api.acapadev.com",
        "ACAPADEV_ENV": "test"
      }
    }
  }
}

4. Confirmar que ficou ligado

Reinicia o cliente e pede ao assistente:

"Qual é o contexto do meu ambiente Acapadev?"

Isso invoca get_environment_context, que devolve o ambiente assumido, o URL da API em uso e o teu perfil. Se receberes o teu nome de volta, está tudo ligado.

Correr a partir do código-fonte

Se quiseres contribuir para o servidor ou inspecionar o que ele faz:

git clone https://github.com/devkussema/acapadev_mcp.git
cd acapadev_mcp
npm install
npm run build
npm start

Resolução de problemas

Sintoma	Causa provável
O servidor não arranca e escreve `ACAPADEV_API_KEY não está definida`	A variável não chegou ao processo. Confirma que está no bloco `env` da configuração do cliente, e não apenas no teu shell.
Todas as ferramentas devolvem `HTTP 401`	Token inválido, revogado, ou expirado. Gera um novo no Portal do Desenvolvedor.
As ferramentas devolvem `HTTP 404` ao indicar um App ID	A app não te pertence, ou estás a usar o `client_id` em vez do ID numérico. Usa `find_app_by_url` ou `list_my_oauth_apps`.
O assistente não vê nenhuma ferramenta	O cliente não recarregou a configuração. Reinicia-o por completo.

← Visão geral Ambientes Test e Live →