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

To configure MCP server tools in OmniRoute, register tool definitions in open-sse/mcp-server/schemas/tools.ts, merge them into the global ALL_TOOLS registry in server.ts, enable the required scopes in 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. 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 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. To enable IO4 tools globally, set the environment variable:

OMNIRoute_MCP_DEFAULT_SCOPES=io4

Alternatively, restrict specific tools using:

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. 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:

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:

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:

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:

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, 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 using Zod schemas for type safety.
• Merge into ALL_TOOLS in open-sse/mcp-server/server.ts to make tools available for routing.
• Configure scopes in 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 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. Finally, define a new scope in 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, 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.

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