Skip to main content
Version: v1

Model Context Protocol (MCP) Server Integration

ActonOS acts as a full-featured MCP Host, allowing agents to seamlessly discover and execute tools exposed by any standard Model Context Protocol server.

1. Supported MCP Transportsโ€‹

  • stdio: The ActonOS daemon spawns the MCP server as a managed sub-process and communicates over standard input/output JSON-RPC.
  • http / sse: Connects to an existing remote MCP server running over HTTP and Server-Sent Events.

2. Adding an MCP Serverโ€‹

Register a server from the Tools page or with POST /api/tools/mcp. Configurations are stored in the ActonOS database (not a JSON file on disk). Connecting or disconnecting an MCP server may return 202 Accepted until an operator approves the change.

{
  "id": "github-mcp",
  "name": "GitHub MCP",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "enabled": true
}

For workspace documents, prefer the built-in native_workspace_* tools. Those keep original filenames. Do not point a filesystem MCP server at /data/workspace โ€” that folder stores internal IDs, not the names you see on the Workspace page.

3. Tool Collision Handling & Sandboxingโ€‹

  • Name Spacing: ActonOS automatically namespaces tools to prevent naming collisions (e.g., mcp_filesystem_read_file).
  • Atomic Rollback: If a newly registered server declares a conflicting tool signature that breaks an existing manifest, ActonOS rolls back registration and alerts the operator.