MCP

Como um assistente de IA pode criar e gerenciar seus bots e ler seus sinais pelo servidor MCP do Okkana: a conexão, as chaves e escopos, as ferramentas e como manter tudo seguro.

O Model Context Protocol (MCP) é um jeito padronizado de um assistente de IA usar ferramentas que ficam num servidor. O assistente, como o Claude Code, o Cursor ou o VS Code, é o cliente. Ele lê a lista de ferramentas que o servidor oferece, escolhe uma quando o seu pedido precisa e envia os argumentos. O servidor executa a ferramenta e devolve o resultado.

O Okkana mantém um servidor MCP para os seus bots e os seus sinais. O assistente pode listar seus bots, ler os sinais que eles geraram e, se você permitir, criar e alterar bots. Cada chamada passa pelas mesmas verificações da API.

O servidor só oferece ferramentas. Não tem dados de mercado e nunca envia ordens.

Crie uma chave de API no seu perfil e copie na hora: ela aparece uma única vez e começa com okk_. A chave leva os escopos que você escolheu, e o servidor MCP usa as mesmas chaves da API.

Depois entregue duas coisas ao seu cliente: o endereço do servidor, /mcp no host da API, e um header Authorization: Bearer com a chave. O transporte é Streamable HTTP, por isso o Claude Code recebe --transport http. O Cursor e o VS Code leem esses mesmos dois valores no arquivo de configuração de MCP; confira na documentação do cliente o nome e o formato atuais do arquivo.

Só uma chave de API abre este endereço. Uma sessão de login recebe 403.

O servidor é montado a cada requisição só com as ferramentas que a sua chave permite. As três do catálogo, list_metrics, list_templates e list_markets, funcionam com qualquer chave. O bots:read acrescenta list_bots e get_bot. O bots:write acrescenta validate_rule, create_bot, update_bot, set_bot_status, duplicate_bot e delete_bot. O signals:read acrescenta list_signals e get_signal.

Uma ferramenta fora dos escopos da chave não aparece na lista, então o assistente nunca a vê. No perfil, o preset Leitura dá bots:read e signals:read, e Leitura e escrita acrescenta bots:write.

Cada ferramenta leva uma indicação que o cliente consegue ler. Oito são só leitura: os três catálogos, list_bots, get_bot, list_signals, get_signal e validate_rule, que confere uma definição e não guarda nada. Quatro alteram seus dados sem destruí-los: create_bot, update_bot, set_bot_status e duplicate_bot. Uma é destrutiva: delete_bot remove o bot e, pouco depois, seus sinais e histórico. Não dá para desfazer.

As indicações são para o cliente, que decide o que roda sozinho e o que confirma com você. A descrição do delete_bot também diz ao assistente para confirmar com você antes.

O update_bot substitui a definição inteira, então o assistente envia todos os campos. Um novo mercado, direção, regra, cooldown ou rearme inicia uma nova revisão, e os sinais passados mantêm a revisão que os disparou.

Descreva o bot com as suas palavras. O assistente consulta os ids de mercado e as métricas, monta a definição e chama o validate_rule, que faz as mesmas verificações do create_bot e não guarda nada. Se ele responder com erros, o assistente corrige esses campos e tenta de novo.

Em seguida o create_bot salva, e o bot aparece na sua página de Bots como qualquer outro. A direção é sua: o assistente precisa perguntar se você espera que o preço suba, caia, ou se só quer o alerta, porque o Okkana nunca deduz isso pela regra.

Um bot criado sem status fica em rascunho, e só bots ativos monitoram o mercado. Ativar é outra chamada, o set_bot_status, que você pode aprovar separadamente.

Quando uma definição está errada, o validate_rule responde com os problemas por caminho de campo, todos juntos: rule.conditions[1].left.timeframe é o timeframe do lado esquerdo da segunda condição. O assistente lê o caminho e a mensagem e corrige só esses campos.

As causas típicas são um id de métrica que não existe, um timeframe faltando numa métrica que precisa dele, uma métrica que o tipo de mercado não tem, como funding no spot, uma direção de venda (SHORT) num mercado spot, e uma média com lookback fora de 2 a 200. Métricas em percentual são números simples: -3 significa -3%.

Trate a chave como uma senha. Comece com uma chave de leitura, que vê seus bots e sinais mas não altera nada, e crie uma de leitura e escrita só para um assistente que você quer que monte bots. Use uma chave por cliente, para revogar uma sem mexer nas outras. Uma chave revogada falha na hora.

Leia o que o assistente vai fazer antes de aprovar uma escrita, principalmente o delete_bot. Um bot novo é rascunho até alguém ativar.

Uma chave não alcança dados de mercado, o seu webhook, o seu perfil nem as suas outras chaves, e nada aqui envia ordens. Cada chave tem um limite de requisições MCP por minuto, 120 por padrão, e uma conta pode ter 10 chaves ativas por padrão.