Referência

Construa projetos do Mokxi com IA

Deixe o ChatGPT, o Claude ou o Cursor montar um projeto inteiro, placa, componentes, fios e código, e entregar a você um link que abre e roda tudo.

O ChatGPT, o Claude, o Gemini, o Copilot, o Cursor e outros assistentes de IA podem montar um projeto inteiro do Mokxi, a placa, os componentes, os fios e o código, e entregar a você um link que o abre no editor e o roda. Colar e links são grátis e não precisam de conta; o servidor MCP e a chamada HTTP precisam de uma conta do Mokxi, e o Grátis constrói até 10 projetos por dia com eles, enquanto o Pro não tem limite diário. Nada é armazenado até você salvar.

Há quatro caminhos, do mais automático ao mais manual:

  1. MCP (qualquer conta). Adicione o servidor MCP do Mokxi ao seu app de IA. O assistente busca componentes e pinos, parte de um modelo que já funciona, verifica o projeto do jeito que o editor faz, corrige o que está errado e entrega um link.
  2. Colar. Copie o prompt do Mokxi, cole em qualquer assistente de chat, diga o que construir e cole a resposta dele na caixa de Importar do Mokxi.
  3. Um link. Um assistente pode escrever um link que carrega o projeto: https://mokxi.com/app/#ai= seguido do projeto como JSON codificado em URL, ou um que carrega só um sketch: https://mokxi.com/app/#code=.
  4. Uma chamada HTTP (qualquer conta). Um script ou a ação de um GPT personalizado pode fazer POST do projeto em https://mokxi.com/api/ai/project e receber o link de volta.

Os quatro leem o mesmo formato de projeto, abaixo, e rodam as mesmas verificações.

Quando o assistente só escreveu código, há um link mais curto: https://mokxi.com/app/#code= seguido do sketch, codificado em URL. O Mokxi escolhe a placa e liga os componentes que o código menciona. Veja Um link só para código.

Conecte o servidor MCP

O servidor está em https://mokxi.com/mcp. Ele fala MCP sobre Streamable HTTP (do tipo sem estado: cada mensagem é um POST, não há fluxo de eventos). Qualquer cliente pode se conectar e listar as ferramentas; chamar uma ferramenta exige login numa conta do Mokxi, em qualquer plano. Há duas formas de entrar:

  • Entre pelo app. Um app que aceita só uma URL (Claude, ChatGPT e outros) abre uma página do Mokxi na primeira vez que chama uma ferramenta. Entre no Mokxi ali, confira o nome do app e escolha Permitir. O app fica conectado até você desconectá-lo em Apps de IA conectados na sua página da conta.
  • An API token. Make one under API tokens on your página da conta; ele começa com mkx_. Send it as an Authorization: Bearer header.

No Grátis, um assistente pode construir até 10 projetos por dia com o servidor (create_project; a contagem recomeça à meia-noite UTC), e todas as outras ferramentas não têm limite diário. O Pro não tem limite diário, e o mesmo vale para todo plano que inclui o Pro: o preço de estudante, o Pro vitalício, um passe, uma vaga numa turma paga e um teste do Pro. Sem login, ou depois do limite diário do Grátis, uma chamada de ferramenta responde com uma linha dizendo isso. O servidor lê só o catálogo de componentes, as placas e os modelos que o editor traz, e não armazena nada. Um cliente que precise de um servidor SSE não funciona com ele.

Claude (claude.ai e o app para desktop)

Configurações, Conectores, Adicionar conector personalizado. Dê a ele o nome Mokxi e a URL:

https://mokxi.com/mcp

Na primeira vez que o Claude chama uma ferramenta, ele abre a página de login do Mokxi. Entre e escolha Permitir.

Claude Code

claude mcp add --transport http mokxi https://mokxi.com/mcp --header "Authorization: Bearer mkx_your_token"

ChatGPT

Em Configurações, ative o modo de desenvolvedor em Conectores e depois adicione um conector com a URL https://mokxi.com/mcp. Escolha OAuth como forma de login e autorize na página do Mokxi que abre, ou forneça seu token de API como bearer token ou chave de API.

Cursor

Em .cursor/mcp.json (o do projeto, ou ~/.cursor/mcp.json para todos os projetos):

{ "mcpServers": { "mokxi": { "url": "https://mokxi.com/mcp", "headers": { "Authorization": "Bearer mkx_your_token" } } } }

VS Code (GitHub Copilot)

Em .vscode/mcp.json:

{ "servers": { "mokxi": { "type": "http", "url": "https://mokxi.com/mcp", "headers": { "Authorization": "Bearer mkx_your_token" } } } }

Gemini CLI

gemini mcp add --transport http mokxi https://mokxi.com/mcp --header "Authorization: Bearer mkx_your_token"

Ou em settings.json:

{ "mcpServers": { "mokxi": { "httpUrl": "https://mokxi.com/mcp", "headers": { "Authorization": "Bearer mkx_your_token" } } } }

Qualquer outro cliente MCP

Adicione um servidor remoto do tipo Streamable HTTP em https://mokxi.com/mcp. Um cliente que segue as regras de login do MCP (OAuth 2.1 com PKCE e registro dinâmico de cliente) encontra tudo de que precisa na resposta 401 do servidor e em https://mokxi.com/.well-known/oauth-protected-resource. Qualquer outro cliente envia o cabeçalho Authorization: Bearer e o seu token de API. O servidor fala as versões de protocolo 2025-11-25, 2025-06-18, 2025-03-26 e 2024-11-05, e o cartão dele está em https://mokxi.com/.well-known/mcp.json.

O que pedir

Diga o que você quer montar e peça o link do Mokxi:

  • "Monte para mim uma luz noturna num Arduino Uno que acende um LED quando escurece, e me dê o link do Mokxi."
  • "Mostre como um sensor de distância HC-SR04 é ligado a um ESP32, com um código que imprime a distância. Abra no Mokxi."
  • "Aqui está o meu sketch. Ligue os componentes de que ele precisa numa Nano e me dê um link do Mokxi para eu ver rodando."
  • "Faça um semáforo em MicroPython numa Raspberry Pi Pico no Mokxi."
  • "Meu servo só dá uma tremidinha. Coloque este código e esta ligação no Mokxi para eu ver o que o pino está fazendo."

O assistente deve responder com um link que começa com https://mokxi.com/app/. Abra-o e o projeto aparece montado, ligado e rodando. Se ele te der o projeto em JSON sem link, peça o link, ou cole o JSON em Importar.

As ferramentas

Ferramenta O que faz
get_project_format As regras do formato, os componentes e placas comuns com seus pinos, e um exemplo
list_boards Cada placa que o Mokxi roda, seu tipo, o código que aceita e seus pinos
search_parts Componentes pelo que são ("oled", "sensor de temperatura"), com pinos e configurações do catálogo do simulador
get_part Um componente completo: pinos, configurações com faixas e unidades, e como um modelo do Mokxi o liga
get_example Um projeto inteiro funcionando para uma placa, um componente ou ambos, tirado dos modelos do Mokxi, para o assistente alterar
validate_project A verificação própria do editor num projeto, com cada problema indicado por componente e pino
create_project O link que abre o projeto e o roda, desde que não tenha erros
create_code_link Um link que abre um sketch numa placa, para código ainda sem circuito pronto

Todas as ferramentas só leem. O link carrega o projeto inteiro na parte do endereço depois do #, que o navegador nunca envia a um servidor, então nada é salvo em lugar nenhum e os projetos do seu plano não são tocados. Quem receber o link abre-o sem conta nenhuma. Aberto, o projeto é seu para salvar, alterar ou fechar.

get_example tem um projeto inicial para a maioria das placas e componentes, não para todos. Quando um componente não tem modelo na placa pedida, ele traz o componente em outra placa e diz o que mudar. create_code_link aceita um sketch de até 24.000 caracteres.

O servidor tem limite de requisições por endereço, como toda rota pública do Mokxi: 60 requisições de uma vez e depois uma por segundo, e 20 verificações de projeto, projetos iniciais ou links de uma vez e depois um a cada cinco segundos.

Um link criado aqui indica de onde veio: ele tem utm_source=mcp e, quando seu app de IA informa seu nome ao servidor, esse nome também. É assim que o Mokxi conta quantas pessoas chegam por assistentes de IA. Nada sobre você ou sua conversa vai nele.

Colar de um chat

In the editor, open Import (or go to mokxi.com/import) e abra Paste from ChatGPT or Claude. Press Copy prompt for your AI, paste it into the assistant, and add what you want to build. Paste the whole reply back into the Import box: Mokxi finds the project in it, lays it out and wires it.

Se algo no projeto estiver errado, ele ainda abre com tudo o que estava certo, e o relatório lista cada problema por componente e pino. Copiar para sua IA copia a lista com um pedido de correção, pronto para colar de volta.

O formato do projeto

Um projeto é um objeto JSON:

{
  "format": "mokxi-ai/1",
  "name": "Button and LED",
  "board": "uno",
  "parts": [
    {"id": "led1", "type": "led", "props": {"color": "red"}},
    {"id": "r1", "type": "resistor", "props": {"value": 220}},
    {"id": "btn1", "type": "pushbutton"}
  ],
  "wires": [
    ["board.13", "r1.1"],
    ["r1.2", "led1.A"],
    ["led1.C", "board.GND"],
    ["board.2", "btn1.1a"],
    ["btn1.2a", "board.GND"]
  ],
  "code": {
    "sketch.ino": "void setup() {\n  pinMode(13, OUTPUT);\n  pinMode(2, INPUT_PULLUP);\n}\n\nvoid loop() {\n  // The button pulls pin 2 to ground when pressed.\n  digitalWrite(13, digitalRead(2) == LOW ? HIGH : LOW);\n}\n"
  }
}
Campo O que contém
format Sempre "mokxi-ai/1". Diz ao Mokxi o que é uma colagem.
name O nome do projeto, com até 120 caracteres.
board O tipo da placa, como "uno", "nano", "esp32" ou "pico" (list_boards tem todos). null para um circuito sem placa.
parts Todos os componentes menos a placa. Cada um tem um id (uma letra, depois letras, dígitos, _ ou -), um type e props opcionais.
wires Pares de pontas, ["partId.pin", "partId.pin"]. A placa é board, então board.13 é o pino 13 dela. Um terceiro item pode indicar uma cor: red, black, green, blue, yellow, purple, cyan ou pink.
code Os arquivos da placa, por nome: {"sketch.ino": "..."} para um sketch de Arduino, ou {"main.py": "..."} para MicroPython numa Raspberry Pi Pico.

Não há coordenadas nem protoboard. O Mokxi coloca a placa à esquerda e os componentes em fileiras ao lado, mantendo juntos os componentes ligados entre si, e passa cada fio do jeito que o canvas faz. Ligue cada pino direto ao pino de destino.

Pins

Um pino é escrito do jeito que o componente o nomeia: A e C num LED, 1 e 2 num resistor, 1a, 1b, 2a e 2b num botão de pressão, VCC, TRIG, ECHO e GND num HC-SR04. get_part lista os pinos de cada componente, e o arquivo de cada componente no pacote de conhecimento também.

A board's pins can be written the way code names them: on an Uno, board.D13 is board.13; on an ESP32 DevKit, board.GPIO2 is board.D2; on a Pico, board.15 is board.GP15 and board.A0 is board.GP26. Upper and lower case do not matter where they do not change the pin.

Configurações

props são as configurações do componente, como o painel de propriedades as mostra. Números são números simples: o value de um resistor está em ohms, o de um capacitor em microfarads, o de um indutor em milihenries. O Mokxi também lê "4.7k" ou "100nF" e converte, com uma nota. get_part dá a faixa, a unidade e as opções de cada configuração.

Mais de uma placa

Coloque cada placa em parts, deixe board de fora (a primeira é board num fio) e dê a code um conjunto de arquivos por id de placa:

{
  "format": "mokxi-ai/1",
  "name": "Two Unos talking",
  "parts": [
    {"id": "a", "type": "uno"},
    {"id": "b", "type": "uno"}
  ],
  "wires": [["a.1", "b.0"], ["b.1", "a.0"], ["a.GND", "b.GND"]],
  "code": {
    "a": {"sketch.ino": "void setup() { Serial.begin(9600); }\nvoid loop() { Serial.println(\"hi\"); delay(1000); }\n"},
    "b": {"sketch.ino": "void setup() { Serial.begin(9600); }\nvoid loop() { if (Serial.available()) Serial.write(Serial.read()); }\n"}
  }
}

O que é verificado

A verificação é a mesma do editor, então validate_project, a caixa de Importar e um link dizem as mesmas coisas.

Erros impedem create_project até serem corrigidos:

  • um tipo de componente que o Mokxi não tem, com o mais parecido que ele tem ("Você quis dizer ws2812?")
  • um pino que o componente não tem, com os pinos que ele tem
  • um fio para um componente que não está no projeto
  • uma configuração que o componente não tem, ou um valor fora da sua faixa
  • uma protoboard (deixe de fora), ou uma placa que o Mokxi desenha mas ainda não simula
  • um fio direto do pino de alimentação de uma placa ao seu terra
  • um nome de arquivo com pasta no meio, ou um sketch Arduino sem arquivo .ino

Vale dar uma olhada nos avisos, mas eles não impedem: um componente sem nada ligado, um componente com uma perna só ligada, uma placa sem código, um sketch sem setup() ou loop(), e um #include de uma biblioteca que o Mokxi não tem.

O Mokxi aceita até 150 componentes, 400 fios e 20 arquivos de código por projeto aqui, e links de até cerca de um megabyte. Passando de uns 8.000 caracteres, alguns apps de chat cortam o link; o JSON do projeto colado na caixa de Importar sempre funciona.

create_project e POST /api/ai/project devolvem um link como https://mokxi.com/app/?utm_source=mcp#ai=1...: o projeto compactado. Um assistente sem ferramentas pode escrever o próprio: https://mokxi.com/app/#ai= seguido do JSON passado por encodeURIComponent. De qualquer jeito, o editor abre, organiza o layout, mostra o que chegou e roda uma vez que o código compila.

Um sketch sem projeto em volta também abre por um link:

https://mokxi.com/app/#code=<the sketch, URL-encoded>&board=<board>
  • code é o sketch inteiro passado por encodeURIComponent. Codifique também (, ), !, ' e * (%28, %29, %21, %27, %2A), para que um app de chat que torne o link clicável não o encerre antes da hora.
  • board é opcional. É o tipo da placa (list_boards tem todos), como uno, nano, mega2560, esp32, esp32c3 ou pico. Sem ele, o Mokxi adivinha a placa a partir dos includes e dos pinos que o sketch usa.

O editor abre o sketch nessa placa e liga os componentes que o código nomeia: um servo no seu pino de attach, um sensor DHT no seu pino de dados, um LED e um resistor em cada saída, um botão em cada entrada. O que não pôde ser posicionado é listado para a pessoa ligar. Tudo depois do # fica no navegador: não é enviado ao servidor do Mokxi.

Por exemplo, um blink num ESP32:

https://mokxi.com/app/#code=void%20setup%28%29%20%7B%20pinMode%282%2C%20OUTPUT%29%3B%20%7D%0Avoid%20loop%28%29%20%7B%20digitalWrite%282%2C%20HIGH%29%3B%20delay%28500%29%3B%20digitalWrite%282%2C%20LOW%29%3B%20delay%28500%29%3B%20%7D&board=esp32

Use #ai= quando você conhece a ligação e a quer exatamente como escrita, e #code= quando o código é tudo o que existe. A pessoa também pode colar o código, ou uma resposta inteira do chat, na caixa em https://mokxi.com/import/ai-code. Pelo MCP, create_code_link escreve este link.

POST /api/ai/project takes the project as its body (or as {"project": ...}) and answers {"ok": true, "url": "...", "summary": "...", "warnings": [...]}, or 422 with {"error": "invalid_project", "ok": false, "errors": [...]}. Like the MCP server, it works on every plan and cannot be called without a token: send the API token of your account as Authorization: Bearer mkx_.... Make the token under API tokens on your página da conta. Sem um, ele responde 401 with {"error": "token_required", ...} and a line saying how to get one. On Free it counts toward the same 10 projects a day as create_project, and past them it answers 429 with {"error": "daily_limit", ...}; Pro has no daily limit. The sign-in an AI app does for the MCP server does not work here. It accepts calls from any origin.