Servidor MCP

O ShvIA pode atuar como um servidor Model Context Protocol (MCP), para que qualquer cliente MCP use as ferramentas do ShvIA: buscar numa base de conhecimento, buscar na sua memória, ler uma skill, resumir o seu uso. Ele roda como você, com as suas permissões, e toda chamada é registrada com o nome da ferramenta e o resultado.

Conecte#

• URL: https://ai.shvia.org/api/v1/mcp
• Método: POST, uma mensagem JSON-RPC 2.0 por requisição.
• Auth: a sua chave de API, em Authorization: Bearer ou X-API-Key.
• Transporte: requisição e resposta simples. Não há streaming, nem id de sessão, nem lote, nem GET.

O servidor declara apenas a capacidade tools. Ele não tem recursos nem prompts. Um cliente que pede resources/list ou prompts/list recebe o erro JSON-RPC -32601.

Como você registra o servidor depende do cliente. A maioria recebe a URL e um header. Para um cliente que aceita um servidor MCP por HTTP, fica assim:

{
  "mcpServers": {
    "shvia": {
      "type": "http",
      "url": "https://ai.shvia.org/api/v1/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

A sintaxe exata da configuração é do cliente. Consulte a documentação dele para saber como ele nomeia um servidor HTTP e os headers.

A troca de mensagens#

initialize#

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"shvia","version":"2.114.2"},"instructions":"…"}}

O servidor sempre responde com a versão de protocolo 2025-06-18, seja qual for a que o cliente pede, e ignora o resto de params. serverInfo.version é a versão do gateway em produção. instructions é um texto para o modelo, escolhido pelo operador.

notifications/initialized#

Uma mensagem sem id é uma notificação. O servidor a responde com 204 No Content e um corpo vazio. Um cliente que insiste em 202 Accepted para notificações pode reclamar.

tools/list#

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

O resultado é {"tools": [{"name", "description", "inputSchema"}, …]}: só as suas ferramentas, sem paginação.

tools/call#

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"usage_summary","arguments":{"days":7}}}

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"…"}],"isError":false}}

O resultado é sempre uma lista de conteúdo text. Uma ferramenta que falha devolve isError: true com o motivo em texto, e ainda responde com HTTP 200. O texto de um resultado é cortado em 8000 caracteres por padrão, com uma nota no final.

Cada chamada roda uma ferramenta uma vez. Não há laço, nem limite de rodadas, nem streaming.

As ferramentas#

Chame tools/list para conhecer o seu conjunto: a lista depende da instalação e do grupo da sua conta. Estas são as ferramentas que funcionam por MCP:

As descrições e os textos de erro das ferramentas são escritos em português, seja qual for o idioma que você usa. O conteúdo que uma ferramenta devolve, como trechos da base de conhecimento, é dado que vem de outras fontes, então trate-o como texto não confiável nos seus prompts.

Erros#

Os erros de protocolo são erros JSON-RPC dentro de um HTTP 200:

Uma ferramenta que existe mas não está na sua lista não é um erro do protocolo: a chamada devolve isError: true e um texto dizendo que você não pode usá-la.

A autenticação e os limites de requisições são HTTP puro: 401 sem uma chave válida, e 429 acima de 300 requisições por minuto. O MCP não tem limite próprio.

Ferramentas por REST#

As mesmas ferramentas estão disponíveis sem o MCP.

GET/api/v1/agent/tools#

Lista as suas ferramentas, com name e description, e sem schemas:

{ "enabled": true, "data": [{ "name": "kb_search", "description": "…" }], "max_rounds": 8 }

POST/api/v1/agent/run#

Roda um laço curto de agente no servidor: o modelo pode chamar as suas ferramentas por algumas rodadas, e você recebe o texto final. Envie message (obrigatório, até 20000 caracteres) e, opcionalmente, profile_name ou model. Um conversation_id seu é aceito só para marcar o registro das chamadas de ferramenta: nenhum histórico é carregado. Nada passa de uma chamada para a outra.

{ "text": "…", "rounds": 3, "tool_calls": 2, "stopped_by": "final", "model": "claude-sonnet-4-6", "server": "anthropic", "error": null }

stopped_by é final num fim normal. Os outros valores (loop_guard, max_rounds, budget, tree_budget, error) querem dizer que o texto pode estar parcial. Cada rodada é uma chamada a modelo que é medida, então uma requisição pode custar até 8 chamadas a modelo. O teto é 5 requisições por minuto por padrão, contadas no mesmo contador por conta dos outros endpoints limitados (veja limites e cotas), então ele pode ser atingido mais cedo. Quando não há ferramentas para a sua conta, ele responde 422 com error: no_tools, e quando o operador desligou o laço, responde 503.