How the MCP Server is Implemented in OmniRoute to Support 110 Tools Across 33 Scopes

The OmniRoute MCP server exposes 110 internal I/O tools via a JSON-RPC 2.0 interface by dynamically registering tool modules from open-sse/mcp-server/tools/ and enforcing granular access controls through 33 distinct permission scopes defined in scopeEnforcement.ts.

The diegosouzapw/OmniRoute repository implements a high-performance Multicall Protocol (MCP) server that centralizes access to over 110 internal tools through a unified JSON-RPC endpoint. Located under open-sse/mcp-server/, this architecture separates concerns between HTTP transport, authentication, scope enforcement, and tool discovery to deliver secure, scalable remote procedure calls across 33 functional domains.

Core Architecture of the MCP Server

The implementation follows a layered architecture where each component handles a specific aspect of the request lifecycle. According to the source code in diegosouzapw/OmniRoute, the server is composed of seven primary modules working in concert.

HTTP Transport and Authentication Layer

The [httpTransport.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/httpTransport.ts) file implements the low-level HTTP listener that parses incoming JSON-RPC 2.0 payloads and manages request timeouts and abort signals. It exposes the /api/mcp endpoint and handles the wire protocol serialization.

Authentication logic resides in [httpAuthContext.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/httpAuthContext.ts), which extracts caller identity from JWT tokens, API keys, or internal authentication headers. This module constructs a CallerIdentity object that downstream components use for permission verification.

Scope Enforcement Mechanism

The [scopeEnforcement.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/scopeEnforcement.ts) file implements the permission matrix that defines the 33 functional scopes. Each scope corresponds to a specific domain such as skill, pool, plugin, memory, radar, compression, githubSkill, notion, obsidian, localCorpus, gamification, agentSkill, pickFastestModel, advanced, a2aLifecycle, audit, pricingSync, cache, dbHealth, createCombo, routingStrategy, pricing, descriptionCompressor, runtimeHeartbeat, toolSearch, toolCount, toolCardinality, toolResult, toolDefinition, providerEnums, ccrTools, and radarCatalog.

Every tool implementation explicitly declares its required scopes. Before executing any tool method, the enforcement layer validates that the caller's granted scopes—derived from JWT claims or API-key policies—encompass all required permissions. Unauthorized calls receive an immediate rejection before reaching business logic.

Dynamic Tool Registry and Catalog

The [toolSearch/register.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/toolSearch/register.ts) module discovers all tool implementations under open-sse/mcp-server/tools/ and registers them with the RPC dispatcher. It builds a method-to-tool mapping that enables runtime routing.

Tool metadata is aggregated in [catalog.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/catalog.ts), which serves a machine-readable JSON description of each tool's name, parameters, and required scopes. Clients query this catalog to discover available capabilities without hardcoding method names.

The [runtimeHeartbeat.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/runtimeHeartbeat.ts) component emits periodic health metrics and latency statistics, enabling monitoring dashboards to track the performance of the 110 registered tools.

JSON-RPC Request Processing Flow

The MCP server processes incoming requests through a strict five-phase pipeline defined in the source architecture:

1. Request Ingestion: The transport layer in httpTransport.ts receives the HTTP POST request on port 20128 and unmarshals the JSON-RPC payload.
2. Identity Extraction: httpAuthContext.ts validates the bearer token and constructs the CallerIdentity object containing the caller's granted scopes.
3. Scope Verification: scopeEnforcement.ts cross-references the requested method's required scopes against the caller's permissions, rejecting insufficient privileges with a 403-equivalent JSON-RPC error.
4. Tool Dispatch: toolSearch/handler.ts looks up the method name in the registry created by toolSearch/register.ts and forwards the call to the concrete implementation (e.g., tools/memoryTools.ts).
5. Response Serialization: The tool's return value is wrapped in a JSON-RPC 2.0 response object and transmitted back through the HTTP transport.

Practical Implementation Examples

Executing Tool Calls via cURL

The following request invokes the memory.get tool from tools/memoryTools.ts, which requires the memory scope:

curl -X POST http://localhost:20128/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT-TOKEN>" \
  -d '{
        "jsonrpc":"2.0",
        "id":1,
        "method":"memory.get",
        "params":{"key":"session:1234"}
      }'

Using the Official Node.js Client

The @omniroute/open-sse/mcp-client library handles authentication and JSON-RPC plumbing automatically:

import { createMcpClient } from "@omniroute/open-sse/mcp-client";

const client = createMcpClient({
  baseUrl: "http://localhost:20128/api/mcp",
  token: process.env.OMNIROUTE_JWT,
});

async function fetchMemory() {
  const resp = await client.call("memory.get", { key: "session:1234" });
  console.log("Memory value:", resp.result);
}

Registering a Custom Tool

Developers can extend the server by adding new tools under open-sse/mcp-server/tools/ and exporting a registration function:

// open-sse/mcp-server/tools/customTools.ts
import { registerTool } from "../toolSearch/register";

registerTool({
  name: "custom.echo",
  scopes: ["advanced"],
  handler: async ({ params }) => ({ echo: params.message }),
});

After rebuilding the server, the custom.echo method appears in the catalog and is accessible to clients possessing the advanced scope.

Summary

• OmniRoute's MCP server implements a JSON-RPC 2.0 interface in the open-sse/mcp-server/ directory, exposing 110 tools through a single HTTP endpoint.
• Thirty-three permission scopes defined in scopeEnforcement.ts provide granular access control across functional domains like memory, skill, and radar.
• Dynamic registration via toolSearch/register.ts automatically discovers tool modules and builds the method-to-handler mapping at runtime.
• Strict request flow enforces authentication in httpAuthContext.ts and authorization in scopeEnforcement.ts before dispatching to concrete tool implementations.
• Machine-readable catalog served by catalog.ts allows clients to discover tool signatures and required scopes without server-side changes.

Frequently Asked Questions

What communication protocol does the OmniRoute MCP server use?

The server implements JSON-RPC 2.0 over HTTP, accepting POST requests at the /api/mcp endpoint. This protocol standardizes request formatting, batch operations, and error handling across all 110 tools, enabling language-agnostic client implementations.

How does the scope enforcement mechanism prevent unauthorized access?

The scopeEnforcement.ts module intercepts every incoming request and compares the caller's granted scopes—extracted from JWT claims in httpAuthContext.ts—against the scopes declared by the target tool. If the caller lacks any required scope, the server returns a JSON-RPC error response before invoking the tool logic, ensuring zero unauthorized execution.

Can third-party developers register new tools with the MCP server?

Yes, developers can add custom tools by creating new files under open-sse/mcp-server/tools/ and calling registerTool() from toolSearch/register.ts. Each registration must specify the tool's JSON-RPC method name, required scopes from the 33 available options, and an async handler function. The tool becomes available immediately after server restart and appears in the catalog.ts output.

What is the purpose of the runtime heartbeat component?

The runtimeHeartbeat.ts module emits periodic health metrics including tool invocation latency, error rates, and throughput statistics. These metrics enable external monitoring systems to track the performance and availability of the MCP server's 110 tools across all 33 scopes without instrumenting individual tool implementations.

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