Servidor MCP para agentes de IA

O Mockzilla traz um servidor MCP, então um agente de programação consegue subir mocks de API para você. Peça para ele mockar um spec e ele instala a CLI, sobe um servidor e devolve a URL, sem você sair do editor.

Ele roda por npx e precisa de Node 18 ou mais novo. Não tem mais nada para instalar. A metade local funciona sem nenhuma conta do Mockzilla.

Adicione ao seu agente

Claude Code:

claude mcp add -s user mockzilla -- npx -y @mockzilla/mcp@latest

Gemini CLI:

gemini mcp add -s user mockzilla npx -y @mockzilla/mcp@latest

Claude Desktop e Cursor usam um arquivo de configuração. O do Claude Desktop é ~/Library/Application Support/Claude/claude_desktop_config.json, o do Cursor é ~/.cursor/mcp.json, e os dois querem o mesmo bloco:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Reinicie o app depois de editar. O Cursor também faz isso em Settings -> MCP Servers -> Add new MCP server.

Deixe o @latest no comando. Sem ele, o npx reaproveita a primeira versão que ele resolveu um dia, e um reinício nunca pega uma mais nova.

O que o seu agente faz sem conta

Tudo isto roda na sua própria máquina:

• Preparar: check_cli procura a CLI na sua máquina, install_cli baixa ela para o cache da própria ponte, e bridge_status informa se saiu uma ponte mais nova.
• Ler specs: info resume um spec ou um pacote .mockz com a lista completa de caminhos, lint encontra schemas que nenhuma resposta consegue satisfazer, e discover_specs varre uma pasta e informa o que dá para mockar dali.
• Remodelar specs: simplify corta um spec quando ele é pesado demais para mockar direito, e pack transforma uma pasta de serviços em um arquivo .mockz.
• Rodar mocks: serve_locally sobe um servidor sobre um ou vários specs, e em um spec só pode adicionar latência ou respostas de erro. stop_locally para ele, e call_endpoint dispara uma requisição para o agente te mostrar a resposta.
• Mockar sem spec: mock_endpoint fixa um caminho só em uma resposta que você descrever, com list_mock_endpoints e clear_mock_endpoints do lado.
• Ler a documentação: mockzilla_docs_topics, mockzilla_docs_search e mockzilla_docs_read dão ao agente a documentação deste site e a do motor. Elas vêm com a ponte, então ler não precisa de internet nem de login.

O install_cli nunca edita o seu PATH. Ele guarda a própria cópia, então uma instalação por brew fica intacta.

Conecte a sua conta

Depois que você entra, o agente também alcança a sua organização: ele lista o que você publicou, navega pelo catálogo e publica uma simulação hospedada que continua respondendo depois que o agente para.

Peça para o seu agente entrar no Mockzilla, ou peça algo hospedado. Ele chama a ferramenta login e o seu navegador abre o login do Mockzilla.

Entre, se ainda não tiver entrado.

Escolha a organização em que o agente vai trabalhar.

Escolha Somente leitura ou Leitura e escrita. Com Leitura e escrita o agente pode publicar. Quem é Viewer só pode escolher Somente leitura.

Clique em Permitir.

O login fica na sua máquina e se renova sozinho, então você faz isso uma vez só.

Depois que você entra, o seu agente pode usar estas ferramentas:

• get_context informa com qual organização e qual acesso o agente trabalha.
• list_sims pagina pelas simulações que você enxerga, com as URLs e os status delas.
• list_catalog_products navega pelo catálogo.
• wait_for_deploy espera um deploy ficar ativo e devolve a URL no ar dele.
• deploy_mock_from_catalog, deploy_mock_from_spec e deploy_mock_from_url criam uma simulação hospedada a partir de uma entrada do catálogo, de um spec colado ou da URL de um spec. Só um login com Leitura e escrita pode usar essas.

Um deploy feito por um agente é um deploy como qualquer outro: ele conta no seu plano e aparece no app.

Para trocar de organização ou de acesso, peça para o agente sair, o que chama logout, e entre de novo. Todo app que você conectou aparece em Configurações, na aba Apps conectados, onde você também pode revogar cada um.

Usar uma API key

Uma máquina sem navegador, como um runner de CI ou um servidor remoto, não consegue abrir a página de login. Nela, dê uma API key para o agente.

Crie a key primeiro. Abra Configurações, depois a aba API keys, e clique em Criar key. Dê o papel Editor se o agente for publicar, ou Viewer se ele só for ler. A key aparece uma vez só.

Depois passe ela como MOCKZILLA_TOKEN. No Claude Code:

claude mcp add -s user mockzilla -e MOCKZILLA_TOKEN=mz_... -- npx -y @mockzilla/mcp@latest

Num arquivo de configuração:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"],
      "env": { "MOCKZILLA_TOKEN": "mz_..." }
    }
  }
}

Com uma key definida, o agente nunca pede para você entrar.

Configurações

Estas variáveis de ambiente são todas opcionais:

• MOCKZILLA_TOKEN é uma API key que o agente usa no lugar do login.
• MOCKZILLA_NO_BROWSER com 1 impede o login de abrir um navegador. O agente te passa o link de login.
• MOCKZILLA_BIN_VERSION fixa qual versão da CLI o install_cli baixa. Por padrão ela segue a ponte.
• MOCKZILLA_MANAGED_PORT é a porta preferida para o servidor do mock_endpoint, 2200 por padrão. Se ela estiver ocupada, uma livre é usada.

Onde ficam os arquivos dela

A ponte guarda a CLI que ela instalou e os endpoints que o mock_endpoint escreveu em ~/.cache/mockzilla-mcp/. Apagar essa pasta reinicia tudo, e uma instalação da CLI por brew não é afetada.

Para limpar só os endpoints mockados, peça para o agente rodar clear_mock_endpoints.

O seu login fica salvo em ~/.config/mockzilla-mcp/. Sair apaga ele.

Para onde ir agora

• Referência da CLI
• Começar pelo catálogo
• Deploy e URLs

A ponte é de código aberto: mockzilla/mockzilla-mcp.