How the MCP Server Integrates with 94 Tools and 30 Auth Scopes in OmniRoute

TLDR: OmniRoute's MCP server exposes a fixed catalog of 94 tools through a unified registry system and enforces granular authentication via 30 configurable scopes that are validated on every request before tool handlers execute.

The diegosouzapw/OmniRoute repository implements a Model-Context-Protocol (MCP) server that aggregates 94 distinct tools across multiple functional domains while enforcing strict scope-based authorization. This architecture ensures that each tool invocation is validated against caller permissions before execution begins, utilizing environment-driven configuration for the 30 available authentication scopes.

Tool Registry Architecture and the 94-Tool Catalog

OmniRoute's MCP server constructs its tool catalog by merging a core registry with dynamic functional groups, then deduplicating the final collection.

Core Registry and Dynamic Tool Groups

The foundation resides in open-sse/mcp-server/schemas/tools.ts, which exports the MCP_TOOLS array containing 34 core tool definitions. Each definition includes a Zod validation schema and a scopes array declaring required permissions.

Additional tool categories are imported in open-sse/mcp-server/server.ts (lines 68-79):

• Memory tools (3 entries)
• Skill tools (4 entries)
• Agent-skill tools (3 entries)
• GitHub-skill integration
• Pool tools (6 entries)
• Gamification tools (8 entries)
• Plugin tools (8 entries)
• Notion tools (6 entries)
• Obsidian tools (22 entries)

The server aggregates these collections and invokes countUniqueMcpTools to populate TOTAL_MCP_TOOL_COUNT (lines 100-104), ensuring exactly 94 unique tools are exposed.

Tool Definition Structure

Each tool follows the McpToolDefinition interface, coupling executable logic with declarative security metadata. The health tool exemplifies this pattern:

// From open-sse/mcp-server/schemas/tools.ts (lines 71-78)
{
  name: "omniroute_get_health",
  description: "Retrieves system health metrics",
  scopes: ["read:health"],  // Declared scope requirement
  schema: z.object({ ... }),
  handler: async (ctx, args) => { ... }
}

Scope-Based Authentication for 30 Auth Scopes

The server implements a zero-trust authorization model where scope enforcement occurs before any tool handler executes.

Declaring and Loading Scopes

Each tool declares its required scopes within the scopes array. The server initializes the global authorization context by reading two environment variables defined in open-sse/mcp-server/server.ts (lines 95-101):

• OMNIROUTE_MCP_SCOPES: Comma-separated list of allowed scopes from the 30 available (e.g., "read:health,write:combos,admin:config")
• OMNIROUTE_MCP_ENFORCE_SCOPES: Boolean flag to toggle strict enforcement

Runtime Scope Enforcement

When a request arrives, the server delegates authorization to evaluateToolScopes imported from open-sse/mcp-server/scopeEnforcement.ts. This utility:

1. Resolves the caller's identity via resolveCallerScopeContext
2. Computes the intersection between the tool's declared scopes and the caller's allowed scopes
3. Returns a 403 Forbidden response if the intersection is empty

This check occurs in the transport layer before business logic executes, ensuring consistent security across all entry points.

Runtime Registration and Tool Cardinality Control

The server instantiates McpServer from @modelcontextprotocol/sdk/server/mcp.js using a compiled tool map linking each name to its definition and Zod validator.

Filtering the Tool Catalog

Operators can prune the 94-tool catalog at startup using environment variables processed by open-sse/mcp-server/toolCardinality.ts:

• MCP_TOOL_DENY: Comma-separated list of tool names to remove
• MCP_TOOL_ALLOW: Whitelist of exclusively permitted tools

The reduceToolManifest function applies these filters after registry assembly but before server initialization, creating a subset based on deployment requirements.

// Conceptual flow from open-sse/mcp-server/server.ts
const ALL_TOOLS = [
  ...MCP_TOOLS,           // 34 core tools
  ...memoryTools,        // 3 tools
  ...skillTools,         // 4 tools
  ...agentSkillTools,    // 3 tools
  ...githubSkillTools,   // Variable count
  ...poolTools,          // 6 tools
  ...gamificationTools,  // 8 tools
  ...pluginTools,        // 8 tools
  ...notionTools,        // 6 tools
  ...obsidianTools,      // 22 tools
];

// Apply cardinality filters
const filteredTools = reduceToolManifest(ALL_TOOLS);

// Initialize with scope enforcement
const server = new McpServer({
  tools: filteredTools,
  enforceScopes: process.env.OMNIROUTE_MCP_ENFORCE_SCOPES === "true",
  allowedScopes: new Set(
    (process.env.OMNIROUTE_MCP_SCOPES ?? "").split(",").map(s => s.trim()).filter(Boolean)
  ),
});

Transport Layer Integration

The MCP server exposes the same 94-tool registry and scope enforcement logic through three distinct transports defined in open-sse/mcp-server/httpTransport.ts:

• StdioServerTransport: For CLI integration and local process communication
• SSE (Server-Sent Events): For streaming HTTP connections requiring real-time updates
• Plain HTTP: For direct REST-style invocations

All transports share the MCP_TOOL_MAP and scope validation pipeline, ensuring that a tool denied via scope restrictions returns 403 regardless of transport method.

// Transport initialization examples
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// CLI transport (omniroute --mcp)
new StdioServerTransport(server).listen();

// HTTP transport with SSE support
import { createMcpHttpServer } from "./httpTransport.ts";
createMcpHttpServer(server).listen(3000);

Summary

• OmniRoute's MCP server aggregates 94 tools from a 34-entry core registry in schemas/tools.ts and dynamic collections for memory, skills, gamification, and integrations.
• 30 authentication scopes are enforced via OMNIROUTE_MCP_SCOPES and validated through evaluateToolScopes before any tool handler executes.
• Tool cardinality control allows runtime filtering via MCP_TOOL_DENY and MCP_TOOL_ALLOW environment variables processed by reduceToolManifest in toolCardinality.ts.
• Unified security model ensures scope checks occur consistently across stdio, SSE, and HTTP transports defined in httpTransport.ts.
• Scope violations return 403 Forbidden immediately, preventing unauthorized access to tool business logic.

Frequently Asked Questions

What are the 94 tools in OmniRoute's MCP server?

The catalog comprises 34 core tools from MCP_TOOLS in open-sse/mcp-server/schemas/tools.ts plus specialized collections: 3 memory tools, 4 skill tools, 3 agent-skill tools, GitHub integration tools, 6 pool tools, 8 gamification tools, 8 plugin tools, 6 Notion tools, and 22 Obsidian tools. These are deduplicated via countUniqueMcpTools in server.ts (lines 100-104) to ensure exactly 94 unique entries.

How do I configure the 30 authentication scopes?

Set the OMNIROUTE_MCP_SCOPES environment variable to a comma-separated list of permitted scopes from the available 30 (e.g., read:health,write:combos,admin:config). Enable enforcement by setting OMNIROUTE_MCP_ENFORCE_SCOPES=true. The server loads these into a Set during initialization and validates every request against tool-declared scopes in scopeEnforcement.ts.

Can I disable specific tools without modifying code?

Yes. Use the MCP_TOOL_DENY environment variable to provide a comma-separated list of tool names to remove, or MCP_TOOL_ALLOW to specify an exclusive whitelist. The reduceToolManifest function in open-sse/mcp-server/toolCardinality.ts filters the registry before the server starts listening, allowing deployment-specific subsets of the full 94-tool catalog.

What happens if a request lacks the required scopes?

The scope enforcement middleware invokes evaluateToolScopes to check the caller's permissions against the tool's declared scopes array. If no intersection exists, the server returns a 403 Forbidden error immediately and prevents the tool handler from executing, ensuring unauthorized requests never reach business logic.

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