Tradução automática, não revista por um falante nativo. O inglês é a referência.

APIs e integraçõesEditar no GitHubFonte: docs/deploy/mcp-http.md

Executando o kshana-mcp por HTTP (hospedagem própria)

Uma passagem que nomeia clientes de IA de terceiros fica de fora aqui; ela está em docs/deploy/mcp-http.md no GitHub.

O Kshana não hospeda um endpoint. Não existe um servidor kshana compartilhado para onde apontar um cliente. Você o executa em sua própria máquina, contêiner ou projeto de nuvem, e é dono do seu controle de acesso e do seu custo. O servidor 0.40.0 é o que está neste repositório: seus valores trazem os rótulos VALIDATED ou MODELLED exatamente como por stdio.

Os padrões seguros#

Controle Comportamento
Endereço de bind Somente loopback (127.0.0.1, ::1). Uma porta sozinha (--http 8080) significa 127.0.0.1:8080.
Non-loopback Exige --allow-remote e um token de portador (bearer) na variável de ambiente KSHANA_MCP_HTTP_TOKEN (16 caracteres ou mais). Sem os dois, o servidor se recusa a iniciar. Com os dois, imprime um aviso de que está escutando além desta máquina.
Autenticação Authorization: Bearer <token> em toda requisição quando um token está definido (pode ser definido também em loopback). Comparado em tempo constante. Ausente ou errado: 401.
Sistema de arquivos Nenhum. As ferramentas de arquivo IQ (iq_*) ficam desligadas no modo HTTP, seja qual for o valor de KSHANA_MCP_IQ_DIR; toda outra ferramenta recebe seu cenário em linha e recusa um que nomeie um arquivo. Nenhum argumento de ferramenta lê ou grava um caminho.
Tamanho do corpo --max-body-bytes, padrão 5 MiB (o limite do cenário é 4 MiB). Acima disso: 413, quer o comprimento seja declarado, quer o corpo seja fragmentado.
Tempo de resposta --request-timeout-secs, padrão 120. Acima disso: 408. Isso limita quanto tempo um chamador espera, não o trabalho: uma execução já em andamento não pode ser interrompida, de modo que continua depois do 408 e termina em segundo plano.
Concorrência --max-concurrent, padrão 8. Além disso, uma requisição recebe 503 com Retry-After de imediato; nenhuma entra em fila.
Pool de trabalho Toda chamada de ferramenta roda em uma thread bloqueante dentro de um pool de --max-concurrent vagas, nunca nos trabalhadores assíncronos, de modo que uma execução longa não pode impedir o servidor de responder. Uma vaga só é liberada quando a própria execução termina, não quando o chamador desiste: execuções abandonadas, portanto, não podem se acumular além do tamanho do pool, e uma chamada que encontra o pool cheio é recusada como ocupada.
Orçamento de trabalho Um cenário que pede muito mais que os exemplos incluídos é recusado antes de rodar: mais de 1000 realizações de Monte Carlo (runs), uma grade de parâmetros com mais de 1000 nós, mais de 5000 execuções-membro (nós da grade vezes realizações) ou uma grade de tempo com mais de 2 milhões de épocas. O erro nomeia o campo a reduzir. O mesmo orçamento vale por stdio; a linha de comando kshana não tem nenhum.
CORS Nenhum cabeçalho Access-Control-* é jamais enviado. Uma requisição com um cabeçalho Origin é recusada (403) a menos que seja nomeada com --allow-origin <scheme://host[:port]>; * não é aceito.
Cabeçalho Host Conferido contra nomes de loopback, ou o endereço de bind mais cada --allowed-host. Atrás de um proxy ou em uma URL de plataforma, passe --allowed-host your.domain. Qualquer outra coisa: 403.
Sessões Nenhuma. Todo POST recebe uma resposta JSON; nenhuma tabela de sessões e nenhum fluxo de eventos enviados pelo servidor é mantido aberto.

O TLS não é terminado por kshana-mcp. Quando ele é alcançável além de uma máquina, ponha HTTPS à frente dele (o TLS da sua plataforma, ou um proxy reverso) e mantenha o token em segredo; um token de portador sobre HTTP simples pode ser lido na rede.

Local#

kshana-mcp --http 127.0.0.1:8080

Configuração do cliente (um cliente por URL; acrescente o cabeçalho apenas quando um token estiver definido):

{ "mcpServers": { "kshana": { "url": "http://127.0.0.1:8080/mcp",
    "headers": { "Authorization": "Bearer ${KSHANA_MCP_HTTP_TOKEN}" } } } }

Docker#

export KSHANA_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8080:8080 -e KSHANA_MCP_HTTP_TOKEN \
  ghcr.io/ashfordeou/kshana-mcp:0.40.0 \
  --http 0.0.0.0:8080 --allow-remote --allowed-host localhost:8080 --allowed-host 127.0.0.1:8080

Dentro do contêiner o servidor precisa escutar em 0.0.0.0, de modo que precisa de --allow-remote e do token. Publicar a porta como 127.0.0.1:8080:8080 a mantém em sua máquina; retire o 127.0.0.1: apenas quando pretender expô-la e, nesse caso, termine o TLS à frente dela. docker compose e modelos para Fly.io e Cloud Run estão em mcp-http/.

Modelos (você os implanta; o Kshana não executa nenhum)#

Cada um executa a imagem publicada, define --allowed-host como o nome de host da plataforma que você substitui no arquivo e conta com a plataforma para o HTTPS.

Defina um limite de CPU e de memória na plataforma#

O tempo limite, o pool e o orçamento limitam quanto trabalho é admitido, mas uma chamada admitida ainda pode usar um núcleo por muito tempo e um resultado grande pode usar centenas de megabytes. Ponha também um limite rígido no contêiner: os modelos pedem 2 CPUs e 1 GiB (cpus e mem_limit no Compose, [[vm]] no Fly, resources.limits no Cloud Run). Mantenha --max-concurrent igual ou abaixo do número de CPUs.

O que ele não é#

  • Não é um serviço multi-inquilino. Quem tiver o token executa simulações em seu hardware; não há cotas por usuário além dos limites acima.
  • Consultivo, não um equipamento de navegação homologado: o operador continua responsável pela navegação. As saídas do simulador são valores modelados ou validados para análise, como em todo o resto do Kshana.