ovos-tool-adapters

Bridges MCP (Model Context Protocol) and UTCP (Universal Tool Calling Protocol) servers into the OVOS agentic loop as standard ToolBox plugins.

Configure an MCP or UTCP server in your persona JSON. The agent loop then consumes it like any other toolbox, with no protocol awareness required.

Install

pip install ovos-tool-adapters[mcp]    # MCP support
pip install ovos-tool-adapters[utcp]   # UTCP support
pip install ovos-tool-adapters[mcp,utcp]

Quick start

Add to your persona JSON:

{
  "name": "researcher",
  "chat_module": "ovos-react-loop",
  "toolboxes": ["ovos-mcp-toolbox"],
  "ovos-mcp-toolbox": {
    "transport": "stdio",
    "command": "uvx",
    "args": ["mcp-server-fetch"],
    "timeout": 30
  }
}

The agent now has access to every tool the MCP server exposes, with the real JSON Schema forwarded to the LLM.

Supported transports

MCP (ovos-mcp-toolbox)

Transport	Config
stdio (subprocess)	"transport": "stdio", "command": "uvx", "args": [...]
SSE	"transport": "sse", "url": "http://..."
Streamable HTTP	"transport": "http", "url": "http://..."

UTCP (ovos-utcp-toolbox)

Any transport supported by the installed UTCP version (HTTP, SSE, CLI, WebSocket, MCP, …):

{
  "toolboxes": ["ovos-utcp-toolbox"],
  "ovos-utcp-toolbox": {
    "utcp_config": {
      "tool_providers": [
        {"name": "search", "provider_type": "http", "url": "http://localhost:8000/tools"}
      ]
    }
  }
}

How it works

• A daemon-thread asyncio event loop keeps MCP/UTCP sessions alive between calls, so there is no reconnect per tool call.
• Each server's JSON Schema is translated to a Pydantic model at discovery time, so the LLM sees the actual input schema.
• Missing mcp/utcp packages degrade gracefully: the toolbox returns an empty tool list and logs a warning, and the agent loop is not affected.

Full documentation: docs/

---

Credits

Developed by TigreGótico for OpenVoiceOS.

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.

---

License

Apache 2.0. See LICENSE.