How to Set Up the OmniRoute MCP Server with 94 Tools and 30 Authorization Scopes

Configure the OMNIROUTE_MCP_SCOPES environment variable with your required permissions from the 30 available scopes, set OMNIROUTE_MCP_ENFORCE_SCOPES=true, and execute npx omniroute --mcp to start the STDIO transport server with all 94 MCP tools automatically registered.

The OmniRoute MCP server in the diegosouzapw/OmniRoute repository exposes 94 Model Context Protocol tools across nine categories including core, memory, skill, and agent capabilities. When you set up the OmniRoute MCP server with 94 tools and 30 authorization scopes, you enable granular access control through environment-based configuration without modifying the underlying TypeScript implementation in open-sse/mcp-server/server.ts.

Prerequisites and Installation

Before starting the server, ensure your environment meets the runtime requirements. The MCP server requires Node.js version 22 or higher to handle the STDIO transport and async scope resolution correctly.

Install the exact dependency tree from the lockfile:

npm ci

This command pulls the versions specified in package-lock.json, including the MCP SDK dependencies required for StdioServerTransport instantiation in open-sse/mcp-server/server.ts.

Configuring the 30 Authorization Scopes

The OmniRoute MCP server implements role-based access control through 30 distinct scopes defined in open-sse/mcp-server/schemas/tools.ts. Each tool declares its required scopes in the scopes field of its McpToolDefinition.

Set these two environment variables to activate enforcement:

• OMNIROUTE_MCP_ENFORCE_SCOPES: Set to "true" to enable scope validation for every tool invocation.
• OMNIROUTE_MCP_SCOPES: A comma-separated list of scopes the caller is permitted to use (e.g., read:health,execute:completions,write:cache).

Create a .env file in your project root:

# Enable strict scope checking

OMNIROUTE_MCP_ENFORCE_SCOPES=true

# Example subset of the 30 available scopes

OMNIROUTE_MCP_SCOPES=read:health,read:combos,execute:completions,read:cache,write:cache,read:proxies,write:proxies,read:compression,read:models,execute:search

The server calculates the total tool count (TOTAL_MCP_TOOL_COUNT) by aggregating core tools, memory, skill, agent-skill, pool, gamification, plugin, Notion, and Obsidian tools—all 94 are registered automatically regardless of scope configuration, but access is gated by the enforcement layer.

Starting the MCP Server

You can initialize the server using either the bundled CLI or a programmatic import.

Option 1: Using the CLI

npx omniroute --mcp

This command invokes the startMcpStdio() function exported from open-sse/mcp-server/server.ts and begins the heartbeat interval that reports version, scope enforcement status, and total tool count.

Option 2: Programmatic Startup

For custom scripts or Docker entrypoints, import the start function directly:

// src/start-mcp.ts
import { startMcpStdio } from "./open-sse/mcp-server/server.js";

await startMcpStdio();

Run with the TypeScript execution engine:

node --import tsx/esm src/start-mcp.ts

Upon startup, the server logs: "[MCP] OmniRoute MCP Server starting (stdio transport)..." followed by the registration summary of all 94 tools.

How Scope Enforcement Works

The authorization logic resides in open-sse/mcp-server/scopeEnforcement.ts and is applied in open-sse/mcp-server/server.ts (lines 111–135). The server builds the allowed-scope set once at startup (MCP_ALLOWED_SCOPES) by parsing OMNIROUTE_MCP_SCOPES.

Each tool handler is wrapped with withScopeEnforcement(toolName, handler, toolScopes):

1. resolveCallerScopeContext extracts the caller-provided scopes from the MCP auth context.
2. evaluateToolScopes compares the tool's required scopes against the allowed set.
3. If the check fails, the handler returns an error: "Error: Insufficient MCP scopes for [tool_name]..." and logs the attempt via logToolCall in open-sse/mcp-server/audit.ts.

This mechanism ensures that even with all 94 tools registered, only callers possessing the specific scopes defined in open-sse/mcp-server/schemas/tools.ts can execute restricted operations like write:cache or execute:completions.

Verifying Tool Registration and Access

Confirm the server is operational by observing the runtime heartbeat emitted from open-sse/mcp-server/runtimeHeartbeat.ts. This periodic signal includes the version string, enforcement flag status, and TOTAL_MCP_TOOL_COUNT (94).

Test a scoped tool invocation using the HTTP-to-STDIO bridge:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool":"omniroute_get_health","args":{}}'

If the caller lacks the read:health scope, the response returns:

{
  "error": "Insufficient MCP scopes for omniroute_get_health. Missing: read:health ..."
}

Successful calls are recorded in the audit log via logToolCall, which captures the tool name, caller identity, and scope validation outcome.

Advanced Configuration

Tool Cardinality Filtering

Beyond scope enforcement, you can filter which tools are exposed using environment variables consumed by open-sse/mcp-server/toolCardinality.ts:

• MCP_TOOL_ALLOW: Comma-separated list of tool names to whitelist (all others denied).
• MCP_TOOL_DENY: Comma-separated list of tool names to blacklist.

This operates independently of the 30-scope authorization system, allowing you to hide tools entirely rather than restricting them via permissions.

Dynamic Scope Injection

For advanced use cases, you can temporarily inject scopes into a specific request context:

import { resolveCallerScopeContext } from "./open-sse/mcp-server/scopeEnforcement.ts";

const extra = req.extra; // MCP auth context
const callerScopes = resolveCallerScopeContext(extra, []).scopes;

// Dynamically add a scope for this request only
callerScopes.add("write:cache");

This pattern is used internally by registerToolSearchTool to grant temporary tool-search permissions without modifying global environment variables.

Summary

• All 94 tools are automatically registered from MCP_TOOLS in open-sse/mcp-server/schemas/tools.ts when the server starts.
• Scope enforcement is controlled by OMNIROUTE_MCP_ENFORCE_SCOPES and the 30 available permissions defined in the tool schemas.
• Access validation occurs in withScopeEnforcement within open-sse/mcp-server/server.ts, rejecting unauthorized calls with explicit error messages.
• Audit trails are written via logToolCall in open-sse/mcp-server/audit.ts for every tool invocation attempt.
• Startup requires only Node.js 22+, npm ci, and either npx omniroute --mcp or a direct call to startMcpStdio().

Frequently Asked Questions

What are the 30 authorization scopes in OmniRoute MCP?

The 30 scopes cover read and write operations across nine functional domains: read:health, read:combos, write:combos, read:quota, execute:completions, read:usage, read:models, execute:search, read:cache, write:cache, read:proxies, write:proxies, read:compression, write:compression, read:catalog, read:skills, write:skills, read:agent, write:agent, read:pricing, write:pricing, read:resilience, write:resilience, read:budget, write:budget, read:security, and write:security. Each tool definition in open-sse/mcp-server/schemas/tools.ts declares which scopes it requires.

How do I enable strict scope checking for all 94 tools?

Set OMNIROUTE_MCP_ENFORCE_SCOPES=true in your environment before starting the server. This activates the evaluateToolScopes function in open-sse/mcp-server/scopeEnforcement.ts, which validates every incoming request against the MCP_ALLOWED_SCOPES set derived from OMNIROUTE_MCP_SCOPES. Without this flag, the server permits all requests regardless of scope configuration.

Can I restrict access to specific tools while keeping all 94 registered?

Yes. While all 94 tools remain registered in the McpServer instance, you can prevent exposure to clients by setting MCP_TOOL_DENY to a comma-separated list of tool names. This filtering occurs in open-sse/mcp-server/toolCardinality.ts before handlers are wrapped with scope enforcement, effectively hiding tools without unregistering them from the protocol layer.

Where does the server log unauthorized scope access attempts?

Unauthorized attempts are logged via logToolCall in open-sse/mcp-server/audit.ts. When evaluateToolScopes detects missing permissions, it returns an "Insufficient MCP scopes" error to the client and simultaneously records the event with the tool name, requested scopes, and caller context to the audit stream, enabling security monitoring and compliance auditing.

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