Set Up MCP Servers on osModa
MCP (Model Context Protocol) is how AI agents connect to external tools and data sources. This guide covers osmoda-mcpd — the Rust daemon that manages MCP server lifecycle on osModa — including how to register MCP servers, configure capabilities, choose between stdio and SSE transport, and connect MCP servers to your agents via the dashboard.
Last updated: March 2026
Key takeaways
- osmoda-mcpd manages MCP server lifecycle: start, stop, auto-restart, tool registration, connection management.
- osModa comes with 83 built-in tools exposed as MCP-compatible capabilities.
- stdio transport: simple, local only, one agent per server instance.
- SSE transport: HTTP-based, network accessible, supports multiple concurrent agent connections.
- Register additional third-party MCP servers via osmoda-mcpd for custom integrations.
What osmoda-mcpd Does
osmoda-mcpd is a Rust daemon that manages the complete lifecycle of MCP servers on your osModa server. Without osmoda-mcpd, you would need to manually start MCP servers, monitor them for crashes, restart them, and configure which agents can access which tools. osmoda-mcpd automates all of this.
Lifecycle management
osmoda-mcpd starts MCP servers when they are needed and stops them when they are not. If an MCP server crashes, osmoda-mcpd restarts it automatically with the same backoff logic as osmoda-watch. MCP servers start on boot alongside your agents.
Tool registration
When an MCP server starts, it declares its available tools. osmoda-mcpd registers these tools in a central catalog that agents can query. Agents see which tools are available without needing to know which MCP server provides them.
Connection management
osmoda-mcpd manages which agents are connected to which MCP servers. It handles connection setup, reconnection on failure, and disconnection cleanup. Every connection event is logged in the audit ledger.
Check osmoda-mcpd status:
# Verify osmoda-mcpd is running systemctl status osmoda-mcpd # View managed MCP servers and their tools journalctl -u osmoda-mcpd --since "10 minutes ago" # Example output: # [osmoda-mcpd] MCP server "filesystem" running (stdio, pid 5201) # [osmoda-mcpd] MCP server "browser" running (sse, port 3001) # [osmoda-mcpd] registered 12 tools from "filesystem" # [osmoda-mcpd] registered 8 tools from "browser" # [osmoda-mcpd] agent "research-agent" connected to "browser"
osModa's 83 Built-In Tools
Every osModa server comes with 83 tools pre-registered and managed by osmoda-mcpd. These cover the core operations an AI agent needs on a server.
File operations: - Read, write, search, watch files and directories - File metadata, permissions, compression Shell execution: - Unrestricted shell (Tier 0) - Sandboxed shell (Tier 1/2) - Output capture, timeout, resource limits Service management: - Start, stop, restart, status for systemd services - Process listing, resource monitoring SafeSwitch deployment: - Atomic deployment with automatic rollback - NixOS generation management - Pre/post deploy health checks Vector + keyword memory: - Store text with vector embeddings - Semantic search across stored memories - Keyword index for exact match retrieval MCP management: - Register, start, stop MCP servers - Connect/disconnect agents to MCP servers - Tool catalog queries Sandbox execution: - Isolated process execution (Tier 2) - Resource-limited containers - Network-restricted execution Fleet coordination: - Multi-server task distribution - Cross-server status queries - Coordinated deployments via osmoda-mesh
These 83 tools are available to agents based on their trust tier. Tier 0 agents access all tools. Tier 1 and Tier 2 agents access only tools within their declared capabilities. See the Agent Security guide for details on trust tier restrictions.
Registering Custom MCP Servers
Beyond the 83 built-in tools, you can register additional MCP servers for custom integrations — database connectors, API wrappers, browser automation, specialized data processing, or any tool your agent needs. Install the MCP server on your osModa machine and register it with osmoda-mcpd.
Example: Install and register a custom MCP server
# 1. Install the MCP server (example: a database connector) cd /opt/mcp-servers git clone https://github.com/example/mcp-postgres.git cd mcp-postgres npm install # 2. Add to NixOS configuration for persistence # /etc/nixos/configuration.nix # environment.systemPackages = with pkgs; [ nodejs_22 ]; # 3. Apply configuration nixos-rebuild switch # 4. Test the MCP server manually first node /opt/mcp-servers/mcp-postgres/index.js --test # osmoda-mcpd will detect and manage the registered server # The server's tools appear in the tool catalog # Agents can then connect to these tools
osmoda-mcpd handles the rest: auto-restart on crash, tool registration, connection management, and audit logging. Your custom MCP server gets the same lifecycle management as the built-in tools.
stdio vs SSE Transport
MCP defines two transport mechanisms for agent-to-server communication. Your choice depends on your architecture — single-agent vs multi-agent, local vs multi-server.
stdio Transport
The MCP server runs as a child process of the agent. Communication happens via stdin/stdout pipes. Simple, no network configuration required, lowest possible latency.
Best for: - Single agent connecting to a single MCP server - Tools that only one agent needs - Maximum simplicity, minimum latency Limitations: - One agent per MCP server instance - Local only (cannot cross server boundaries) - New instance required for each agent connection
SSE (Server-Sent Events) Transport
The MCP server runs as an HTTP service. Agents connect to it over the network using SSE for server-to-client streaming and HTTP POST for client-to-server requests.
Best for: - Multiple agents sharing the same MCP server - Multi-server architectures (via osmoda-mesh) - Tools that need to serve many consumers - Dashboard-accessible tool management Configuration: - MCP server listens on a local port (e.g., 3001) - For cross-server: osmoda-mesh routes traffic - Agents connect via HTTP to localhost:PORT or mesh address
Recommendation: Start with stdio for simplicity. Switch to SSE when you need multiple agents sharing tools or when you scale to a multi-server architecture. osmoda-mcpd manages both transport types identically.
Managing MCP Servers via the Dashboard
The osModa dashboard at spawn.os.moda provides a visual interface for managing MCP server connections. This is the easiest way to configure which agents use which tools without touching the command line.
View registered MCP servers
See all MCP servers running on your server — built-in and custom. View their status (running, stopped, crashed), available tools, and current connections. Monitor resource usage per MCP server.
Connect agents to MCP servers
Select an agent and choose which MCP servers it should connect to. The dashboard shows available tools for each server and lets you selectively enable or disable specific tools per agent.
Monitor MCP events
View MCP server logs, tool invocation history, connection events, and errors. All MCP events are logged in the audit ledger for forensic analysis. Track which agents are using which tools and how frequently.
Frequently Asked Questions
What is MCP (Model Context Protocol)?
MCP is an open protocol created by Anthropic that standardizes how LLMs connect to external tools and data sources. Instead of each agent implementing its own integrations, MCP provides a universal interface. An MCP server exposes tools (functions the LLM can call) and resources (data the LLM can read). osModa uses osmoda-mcpd to manage MCP server lifecycle.
What is osmoda-mcpd?
osmoda-mcpd is the Rust daemon that manages MCP server lifecycle on osModa. It handles starting, stopping, auto-restarting MCP servers, registering their tools, managing connections between agents and MCP servers, and logging all MCP events to the audit ledger. It ensures MCP servers stay running alongside your agents.
What is the difference between stdio and SSE transport?
stdio transport launches the MCP server as a child process and communicates via stdin/stdout — simple, low overhead, but limited to the local machine. SSE (Server-Sent Events) transport runs the MCP server as an HTTP service that agents connect to over the network — works across servers, supports multiple concurrent agent connections, and is the better choice for multi-agent architectures.
Can multiple agents connect to the same MCP server?
Yes, with SSE transport. When an MCP server runs as an HTTP service, multiple agents can connect to it simultaneously. This is how you share tools across agents without running duplicate MCP server instances. stdio transport is one-to-one (one agent per MCP server instance).
What MCP servers come pre-installed on osModa?
osModa comes with 83 built-in tools managed as MCP-compatible capabilities: file operations, shell execution, service management, SafeSwitch deployment, vector and keyword memory, MCP management, sandbox execution, and fleet coordination. You can register additional third-party MCP servers via osmoda-mcpd.
How do I connect an MCP server to my agent via the dashboard?
The osModa dashboard at spawn.os.moda provides a visual interface for managing MCP server connections. You can see registered MCP servers, their available tools, connection status, and link them to specific agents. The dashboard communicates with osmoda-mcpd to manage these connections.
83 Tools, Ready to Use
osModa servers come with osmoda-mcpd and 83 built-in tools pre-configured. Register custom MCP servers for your specific integrations. From $14.99/month.
Explore More Guides