How to Configure the MCP Server with IO4 Tools in OmniRoute

Enable the IO4 tool family in OmniRoute's MCP server by registering the Zod schemas in open-sse/mcp-server/schemas/tools.ts, merging them into the ALL_TOOLS registry in server.ts, and granting the io4 scope via the OMNIRoute_MCP_DEFAULT_SCOPES environment variable or API key configuration.

The MCP (Multi-Component Proxy) server serves as OmniRoute’s core tool-execution layer, exposing built-in tool families through stdio, SSE, and HTTP transports. The IO4 tool suite provides sandboxed file-system operations—read, write, list, and delete—that agents can invoke after proper registration and scope configuration.

Understanding the IO4 Tool Architecture

What Are IO4 Tools?

IO4 tools constitute a specialized tool family providing four file-system handlers: io4_read, io4_write, io4_list, and io4_delete. According to the OmniRoute source code, these handlers are implemented in open-sse/mcp-server/tools/io4.ts and defined using Zod schemas in open-sse/mcp-server/schemas/tools.ts. Each operation executes within the DATA_DIR sandbox, preventing arbitrary host file system access.

Transport Options

The MCP server supports three transport mechanisms for tool invocation:

• stdio – For local CLI integration
• SSE (Server-Sent Events) – For persistent streaming connections
• HTTP – For standard request/response patterns via /api/mcp/sse

Step-by-Step Configuration

1. Verify Tool Definitions

First, ensure the IO4 tool definitions are present in the schema registry. In open-sse/mcp-server/schemas/tools.ts, the IO4 namespace exports Zod schemas for each handler along with their input parameter validations.

2. Register Tools in the Global Registry

The server initialization file open-sse/mcp-server/server.ts imports the IO4 object and merges it into the master ALL_TOOLS map. This map routes incoming requests to the correct handler implementation. Verify that your local copy includes the IO4 import and that the merge operation is present:

// Conceptual representation based on server.ts implementation
import { IO4 } from './schemas/tools';
import { io4Handlers } from './tools/io4';

// ALL_TOOLS combines schema definitions with implementations
const ALL_TOOLS = {
  ...IO4,
  // other tool families...
};

3. Configure Access Scopes

Scopes control which tool families an API key may invoke. The IO4 tools are grouped under the io4 scope, defined in src/shared/constants/mcpScopes.ts.

Set the environment variable to enable IO4 tools by default for all API keys:

OMNIRoute_MCP_DEFAULT_SCOPES=io4

To restrict access to specific IO4 operations, use the granular enablement variable:

OMNIRoute_MCP_ENABLED_TOOLS=io4_read,io4_write,io4_list,io4_delete

4. Launch the Server

Start the MCP server via CLI or as an HTTP endpoint:

• CLI mode: omniroute --mcp
• HTTP endpoint: Accessible at /api/mcp/sse

The server reads the tool registry at startup, binding the IO4 handlers to the transport layers. Note: Any modifications to tool definitions or registry membership require a server restart to take effect.

Usage Examples

Reading Files with io4_read

import { createMcpClient } from '@omniroute/open-sse/mcp-client';

const client = createMcpClient({
  url: 'http://localhost:3000/api/mcp/sse',
  apiKey: 'your-api-key-with-io4-scope',
});

const result = await client.callTool('io4_read', {
  path: 'projects/example.txt', // Relative to DATA_DIR
});
console.log(result.content); // File contents as string

Writing Files with io4_write

await client.callTool('io4_write', {
  path: 'projects/new.txt',
  content: 'Hello from OmniRoute!', // String or base64-encoded buffer
});

Listing Directories with io4_list

const listing = await client.callTool('io4_list', {
  directory: 'projects',
});
console.log(listing.entries); // Array of file/directory names

Deleting Files with io4_delete

await client.callTool('io4_delete', {
  path: 'projects/old.txt',
});

Summary

• IO4 tools provide four sandboxed file operations: read, write, list, and delete
• Configuration requires updating open-sse/mcp-server/schemas/tools.ts for schemas and open-sse/mcp-server/server.ts for the ALL_TOOLS registry
• Access control is governed by the io4 scope in src/shared/constants/mcpScopes.ts
• Environment variables OMNIRoute_MCP_DEFAULT_SCOPES and OMNIRoute_MCP_ENABLED_TOOLS control availability without code changes
• The server validates all inputs via Zod and restricts file access to the DATA_DIR sandbox

Frequently Asked Questions

What transport protocols does the OmniRoute MCP server support?

The server implements three transports: stdio for local process communication, SSE (Server-Sent Events) for real-time streaming connections, and standard HTTP for REST-style requests. All transports access the same ALL_TOOLS registry, allowing IO4 tools to work identically across interfaces.

How do I restrict access to specific IO4 tools rather than the entire family?

Use the OMNIRoute_MCP_ENABLED_TOOLS environment variable to specify a comma-separated allowlist. For example, setting OMNIRoute_MCP_ENABLED_TOOLS=io4_read,io4_list blocks write and delete operations while permitting read-only access.

Where are files stored when using IO4 write operations?

The IO4 handlers operate within a sandboxed directory defined by the DATA_DIR environment variable. All paths provided to io4_write, io4_read, and other handlers are resolved relative to this directory, preventing access to system files outside the OmniRoute data environment.

Do I need to restart the server after modifying tool schemas in tools.ts?

Yes. The MCP server loads the ALL_TOOLS registry into memory at startup, as implemented in open-sse/mcp-server/server.ts. Changes to schema definitions in open-sse/mcp-server/schemas/tools.ts or handler implementations in open-sse/mcp-server/tools/io4.ts require a full process restart to take effect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}