# How to Configure the MCP Server with IO4 Tools in OmniRoute

> Configure the MCP server with IO4 tools in OmniRoute. Register Zod schemas, merge into the ALL_TOOLS registry, and grant the io4 scope to enable the IO4 tool family.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-31

---

**Enable the IO4 tool family in OmniRoute's MCP server by registering the Zod schemas in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts), merging them into the `ALL_TOOLS` registry in [`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/io4.ts) and defined using Zod schemas in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/mcpScopes.ts).

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

```text
OMNIRoute_MCP_DEFAULT_SCOPES=io4

```

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

```text
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`

```typescript
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`

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

```

### Listing Directories with `io4_list`

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

```

### Deleting Files with `io4_delete`

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) for schemas and [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tools.ts)?

Yes. The MCP server loads the `ALL_TOOLS` registry into memory at startup, as implemented in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts). Changes to schema definitions in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) or handler implementations in [`open-sse/mcp-server/tools/io4.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/io4.ts) require a full process restart to take effect.