MCP server

ShvIA can act as a Model Context Protocol (MCP) server, so that any MCP client can use ShvIA's tools: search a knowledge base, search your memory, read a skill, summarize your usage. It runs as you, with your permissions, and every call is logged with the tool name and its outcome.

Connect#

• URL: https://ai.shvia.org/api/v1/mcp
• Method: POST, one JSON-RPC 2.0 message per request.
• Auth: your API key, in Authorization: Bearer or X-API-Key.
• Transport: plain request and response. There is no streaming, no session id, no batching, and no GET.

The server declares only the tools capability. It has no resources and no prompts. A client that asks for resources/list or prompts/list gets the JSON-RPC error -32601.

How you register the server depends on the client. Most take the URL and a header. For a client that accepts an HTTP MCP server, that is:

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

The exact configuration syntax belongs to the client. Check its documentation for how it names an HTTP server and its headers.

The exchange#

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":"…"}}

The server always answers with protocol version 2025-06-18, whatever the client asks for, and ignores the rest of params. serverInfo.version is the version of the deployed gateway. instructions is text for the model, chosen by the operator.

notifications/initialized#

A message with no id is a notification. The server answers it with 204 No Content and an empty body. A client that insists on 202 Accepted for notifications may complain.

tools/list#

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

The result is {"tools": [{"name", "description", "inputSchema"}, …]}: your tools only, with no pagination.

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}}

The result is always a list of text content. A tool that fails returns isError: true with the reason as text, and still answers with HTTP 200. The text of a result is cut at 8000 characters by default, with a note at the end.

Each call runs one tool once. There is no loop, no round limit and no streaming.

The tools#

Call tools/list to learn your own set: the list depends on the installation and on your account group. These are the tools that work over MCP:

The descriptions and the error texts of the tools are written in Portuguese, whatever language you use. The content a tool returns, such as knowledge-base passages, is data that comes from other sources, so treat it as untrusted text in your prompts.

Errors#

Protocol errors are JSON-RPC errors inside an HTTP 200:

A tool that exists but is not in your list is not an error of the protocol: the call returns isError: true and a text that says that you may not use it.

Authentication and request limits are plain HTTP: 401 without a valid key, and 429 past 300 requests per minute. MCP has no limit of its own.

Tools over REST#

The same tools are available without MCP.

GET/api/v1/agent/tools#

Lists your tools, with name and description, and no schemas:

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

POST/api/v1/agent/run#

Runs a short agent loop on the server: the model can call your tools up to a few rounds, and you get the final text. Send message (required, up to 20000 characters) and optionally profile_name or model. A conversation_id of yours is accepted only to tag the log of the tool calls: no history is loaded. Nothing is carried over between calls.

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

stopped_by is final for a normal end. The other values (loop_guard, max_rounds, budget, tree_budget, error) mean the text may be partial. Every round is a model call that is metered, so one request can cost up to 8 model calls. The ceiling is 5 requests per minute by default, on a counter of its own, on top of the 300 per minute (see rate limits and quotas). When there are no tools for your account, it answers 422 with error: no_tools, and when the operator has turned the loop off it answers 503.