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

> Discover how the MCP server in OmniRoute supports 110 tools across 33 scopes. Learn about dynamic tool registration and granular access control for robust I/O management. Explore the implementation details.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: internals
- Published: 2026-08-22

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts) receives the HTTP POST request on port `20128` and unmarshals the JSON-RPC payload.
2. **Identity Extraction**: [`httpAuthContext.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpAuthContext.ts) validates the bearer token and constructs the `CallerIdentity` object containing the caller's granted scopes.
3. **Scope Verification**: [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolSearch/handler.ts) looks up the method name in the registry created by [`toolSearch/register.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolSearch/register.ts) and forwards the call to the concrete implementation (e.g., [`tools/memoryTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tools/memoryTools.ts), which requires the `memory` scope:

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

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

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) provide granular access control across functional domains like `memory`, `skill`, and `radar`.
- **Dynamic registration** via [`toolSearch/register.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolSearch/register.ts) automatically discovers tool modules and builds the method-to-handler mapping at runtime.
- **Strict request flow** enforces authentication in [`httpAuthContext.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpAuthContext.ts) and authorization in [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) before dispatching to concrete tool implementations.
- **Machine-readable catalog** served by [`catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) module intercepts every incoming request and compares the caller's granted scopes—extracted from JWT claims in [`httpAuthContext.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/catalog.ts) output.

### What is the purpose of the runtime heartbeat component?

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