# How to Configure MCP Server Tools in OmniRoute with Over 105 Tools

> Learn to configure MCP server tools in OmniRoute. Integrate over 105 tools by registering definitions, merging into ALL_TOOLS, enabling scopes, and launching the server. Streamline your workflow today.

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

---

**To configure MCP server tools in OmniRoute, register tool definitions in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts), merge them into the global `ALL_TOOLS` registry in [`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/server.ts), enable the required scopes in [`mcpScopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcpScopes.ts), and launch the server via CLI or HTTP endpoint.**

OmniRoute's **MCP (Multi-Component Proxy) server** serves as the central execution layer for its expansive toolkit of over 105 built-in tools. Whether you're enabling file-system operations through the IO4 family or configuring memory and proxy tools, the configuration follows a consistent registry-based pattern. This guide walks you through configuring MCP server tools in OmniRoute using the IO4 tool family as a concrete implementation example.

## Understanding the MCP Server Architecture

The MCP server in OmniRoute supports three transport mechanisms: **stdio**, **SSE (Server-Sent Events)**, and **HTTP**. According to the diegosouzapw/OmniRoute source code, the server exposes built-in tool families—including memory, skill, proxy, and IO operations—through these transports. Each tool family, such as the IO4 tools that provide `read`, `write`, `list`, and `delete` operations, requires explicit registration and scope configuration before becoming available to clients.

## Step-by-Step Configuration of MCP Server Tools

### 1. Register Tool Definitions in the Schema

Tool definitions reside in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts). For the IO4 family, this file exports an `IO4` namespace containing Zod schemas for four handlers: `io4_read`, `io4_write`, `io4_list`, and `io4_delete`. Each schema defines the input parameters required for request validation.

### 2. Merge Tools into the Global Registry

The server initialization file at [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) imports the `IO4` object from the schemas and merges it into the master `ALL_TOOLS` map. This registry serves as the routing table for incoming tool execution requests. Without this step, the tool definitions remain inaccessible to the transport layer.

### 3. Configure Access Scopes

Scopes govern API key permissions for tool invocation. The `io4` scope is defined in [`src/shared/constants/mcpScopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/mcpScopes.ts). To enable IO4 tools globally, set the environment variable:

```bash
OMNIRoute_MCP_DEFAULT_SCOPES=io4

```

Alternatively, restrict specific tools using:

```bash
OMNIRoute_MCP_ENABLED_TOOLS=io4_read,io4_write,io4_list,io4_delete

```

### 4. Start the MCP Server

Launch the server via the CLI command `omniroute --mcp` or expose it as an HTTP endpoint at `/api/mcp/sse`. The server reads the tool registry at startup, meaning any changes to tool definitions require a full restart to take effect.

## Implementing IO4 Tools: Practical Examples

The IO4 tool implementations reside in [`open-sse/mcp-server/tools/io4.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/io4.ts). These handlers operate within the OmniRoute data directory (`DATA_DIR`), providing automatic sandboxing that prevents access to arbitrary host files.

### Reading Files with io4_read

Invoke the read handler through any supported transport:

```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);

```

### Writing Files with io4_write

The write handler accepts string or base64-encoded content:

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

```

### Listing Directories with io4_list

Retrieve directory contents without accessing parent paths:

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

```

### Deleting Files with io4_delete

Remove files within the sandboxed directory:

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

```

## Security Considerations and Sandboxing

All IO4 operations are constrained to the `DATA_DIR` environment path. As implemented in [`open-sse/mcp-server/tools/io4.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/io4.ts), the handlers validate paths to prevent directory traversal attacks. This sandboxing ensures that even with broad scope permissions, tools cannot access sensitive host system files outside the designated data directory.

## Summary

- **Register definitions** in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) using Zod schemas for type safety.
- **Merge into ALL_TOOLS** in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) to make tools available for routing.
- **Configure scopes** in [`src/shared/constants/mcpScopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/mcpScopes.ts) and enable via `OMNIRoute_MCP_DEFAULT_SCOPES` environment variables.
- **Restart required** after any tool registry modifications.
- **Sandboxed execution** ensures IO4 tools operate only within `DATA_DIR`.

## Frequently Asked Questions

### How do I add custom tools beyond the 105+ built-in tools in OmniRoute?

To add custom tools, create a new schema definition in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) following the Zod validation pattern used by IO4. Implement the handler logic in a new file under `open-sse/mcp-server/tools/`, then import and merge your tool namespace into the `ALL_TOOLS` map in [`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/server.ts). Finally, define a new scope in [`mcpScopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcpScopes.ts) and assign it to your API keys.

### What transports does the OmniRoute MCP server support?

The OmniRoute MCP server supports three transports: **stdio** for local process communication, **SSE (Server-Sent Events)** for streaming HTTP connections, and standard **HTTP** for request-response interactions. You can configure the transport mode when starting the server via CLI flags or environment variables.

### Why are my IO4 tools returning permission errors?

Permission errors typically indicate missing scope configuration. Verify that your API key includes the `io4` scope as defined in [`src/shared/constants/mcpScopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/mcpScopes.ts), or that the environment variable `OMNIRoute_MCP_DEFAULT_SCOPES` includes `io4`. Additionally, ensure the tool names match exactly in `OMNIRoute_MCP_ENABLED_TOOLS` if using explicit tool filtering.

### Can I restrict which specific IO4 tools are available to different API keys?

Yes, while scopes control broad tool families, you can further restrict access using the `OMNIRoute_MCP_ENABLED_TOOLS` environment variable to specify a comma-separated allowlist (e.g., `io4_read,io4_list`). For granular per-key restrictions, implement custom middleware in the HTTP entry point at `src/app/api/mcp/[...]/route.ts` to validate tool names against the authenticated key's permissions before dispatching to the MCP server.