MCP Tools Management
Guide to connecting and managing Model Context Protocol (MCP) servers in Sapientia.
The Model Context Protocol (MCP) is an open specification that enables AI models to interface securely with external data repositories, development environments, and system tools.
Sapientia provides a unified management panel to register, inspect, and toggle MCP servers, equipping your local AI agents with direct access to local filesystems, internal databases, and developer utilities.
Supported Transport Protocols
Sapientia implements two standard MCP communication transports:
1. Stdio Transport (CLI Subprocess)
Launches the MCP server as a local child process communicating over standard input/output streams (stdin/stdout):
- Command: Executable binary name (e.g.,
npx,python,docker, or custom standalone binaries). - Arguments: Command-line parameters passed on startup (e.g.,
["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Projects"]). - Environment Variables: Encapsulated environment variables (such as
API_KEYorPATH) scoped strictly to that subprocess.
2. Streamable HTTP Transport (SSE)
Connects to an MCP server exposed over network endpoints:
- Utilizes Server-Sent Events (SSE) for reliable bidirectional communication.
- Ideal for integrating shared team microservices or containers running elsewhere on your local network.
Server Management Lifecycle
1. Registering an MCP Server
- Navigate to the Settings or MCP Management panel in the Sapientia desktop interface.
- Click "Add MCP Server".
- Fill in the server parameters:
- Server Name: A descriptive label for easy identification.
- Transport Type: Choose either
stdioorstreamable-http. - Command & Arguments: Startup binary and argument list for stdio, or full endpoint URL for HTTP streaming.
- Environment Variables: Necessary runtime environment flags supplied as key-value pairs.
- Click "Save & Connect".
2. Capability & Tool Inspection
Once a server connects successfully, Sapientia automatically retrieves its declared schema:
- Displays available tool functions alongside human-readable descriptions.
- Parses the input JSON Schema for each tool to ensure the local LLM generates compliant parameter payloads.
- Surfaces active connection health states (Connected, Connecting, or Error).
3. Enabling & Disabling Servers
Each server card includes a toggle switch to enable or disable it on demand. Toggling a server off closes the background connection without removing your stored credentials or argument configurations.
Integration with Workflows and Chat
Tools from active MCP servers seamlessly extend agent capabilities:
- Workflow Builder Integration:
- Open any Agent Node in the Workflow Builder.
- Switch to the Tools configuration tab.
- Check the specific MCP tools you wish to grant to that agent.
- Autonomous Tool Calling:
- The local model analyzes the incoming user request.
- When external context or operations are required, the model formulates an accurate tool call.
- Sapientia executes the tool locally, formats the output, and returns the result into the model's reasoning loop.
Safety & Local Governance
Invoking local system tools demands strict operational safety:
- Parameter Validation: Function payloads are verified against published JSON schemas before execution.
- Execution Timeouts: Tool invocations enforce configurable execution timeouts to prevent orphaned or frozen processes.
- Human-in-the-Loop Safeguards: For sensitive actions (such as filesystem deletions or shell execution), place a Human Approval Node downstream from the agent to require manual verification before changes are committed.