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, counted on the same per-account counter as the other limited endpoints (see rate limits and quotas), so it can be reached sooner. 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.