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

> Easily set up the OmniRoute MCP server with 94 tools and 30 authorization scopes. Configure environment variables and start the server for effective tool access control.

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

---

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

```bash
npm ci

```

This command pulls the versions specified in [`package-lock.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package-lock.json), including the MCP SDK dependencies required for `StdioServerTransport` instantiation in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```dotenv

# 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

```bash
npx omniroute --mcp

```

This command invokes the `startMcpStdio()` function exported from [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

await startMcpStdio();

```

Run with the TypeScript execution engine:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) and is applied in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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:

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

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