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

> Unlock OmniRoute's MCP server integration: discover its 94 tools and 30 auth scopes. Learn how it ensures secure, efficient access control for every request.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolCardinality.ts).
- **Unified security model** ensures scope checks occur consistently across stdio, SSE, and HTTP transports defined in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.