# How MCP Server Tools Integrate with Notion and GitHub in OmniRoute

> Discover how OmniRoute's MCP server tools integrate with Notion and GitHub. Learn about its central catalog, OAuth scope validation, and request routing for seamless external service management.

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

---

**OmniRoute’s MCP server exposes dedicated toolsets for Notion and GitHub, registering them in a central catalog that validates OAuth scopes and routes requests to service-specific handlers—using SQLite-backed token storage for Notion and a public OAuth client ID for GitHub Marketplace operations.**

The OmniRoute project implements a Multi-Channel Protocol (MCP) server that bridges agent workflows with external SaaS platforms. By modularizing integrations into discrete toolsets defined in `open-sse/mcp-server/tools/`, the server enables secure, scope-gated access to Notion workspaces and GitHub repositories through standardized JSON-RPC interfaces.

## Tool Registration and the Central Catalog

### Bootstrapping the Registry

When the MCP server initialises, it imports tool arrays from service-specific modules and spreads them into the runtime registry. In [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts), the server aggregates core utilities, memory stores, and external service tools into a single array:

```typescript
import { notionTools } from "./tools/notionTools.ts";
import { githubSkillTools } from "./tools/githubSkillTools.ts";

const allTools = [
  ...coreTools,
  ...memoryTools,
  ...skillTools,
  ...notionTools,
  ...githubSkillTools,
  // …other groups
];

```

### Runtime Tool Discovery

The aggregated array feeds into the **tool catalog** ([`mcp-server/toolSearch/catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcp-server/toolSearch/catalog.ts)), which clients query via the `mcp_list_tools` RPC method. Each catalog entry contains the tool name, description, input JSON schema, and required permission scope, allowing the client to discover available capabilities before invocation.

## Notion Integration: Token-Based API Access

### Token Persistence Layer

Notion integration relies on a `token_v2` cookie extracted from browser authentication. The [`src/lib/db/notion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/notion.ts) module persists this sensitive value in a SQLite `key_value` table using `INSERT OR REPLACE`, ensuring the token survives server restarts:

```typescript
await db.run(`INSERT OR REPLACE INTO key_value (key, value) VALUES ('notion_token', token)`);

```

### Configuration via REST Endpoints

Users configure the Notion connection through a thin REST layer defined in [`src/app/api/settings/notion/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/settings/notion/route.ts). The endpoint supports three operations:

- `GET /api/settings/notion` – Returns a JSON object indicating connection status: `{ connected, hasToken }`
- `POST /api/settings/notion` – Validates and stores the `token_v2` string
- `DELETE /api/settings/notion` – Removes the stored token from the database

### API Client and Tool Handlers

All six Notion tools—`notion_search`, `notion_get_page`, `notion_list_block_children`, `notion_query_database`, `notion_get_database`, and `notion_append_blocks`—delegate to [`src/lib/notion/api.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/notion/api.ts). This wrapper reads the stored token, injects it into the HTTP `Cookie` header, and forwards requests to the official Notion API. The handlers are defined in [`open-sse/mcp-server/tools/notionTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/notionTools.ts), where each function translates MCP input parameters into REST calls and returns paginated JSON responses.

## GitHub Integration: Skill-Collector Pattern

### OAuth Client Resolution

Rather than embedding secrets directly, the GitHub integration uses `resolvePublicCred()` from [`open-sse/utils/publicCreds.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/publicCreds.ts) to obtain a public GitHub-Copilot OAuth client ID. This approach keeps credentials out of version control while enabling unauthenticated queries against the GitHub Marketplace.

### Skill Lifecycle Tools

The GitHub toolset implements a three-phase skill-collector workflow exported from [`open-sse/mcp-server/tools/githubSkillTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/githubSkillTools.ts):

- **`omniroute_github_skills_search`** – Queries the GitHub Marketplace for agent-skill repositories matching a text query, returning metadata like `fullName`, `stars`, and relevance `score`.
- **`omniroute_github_skills_scan`** – Downloads a candidate repository’s README and source files, scanning for disallowed patterns (e.g., malicious shell commands) before installation.
- **`omniroute_github_skills_install`** – Calculates a safe installation path and returns an `action: "planned"` response; the actual `git clone` operation is performed asynchronously by a separate API route at `/api/github-skills`.

### Permission Scopes

Access to GitHub tools is gated by granular scopes. Read operations require `read:github`, while the install tool demands `write:github`. The MCP authorization middleware validates these scopes against the request’s JWT before executing the handler.

## Practical MCP Tool Invocations

### Searching Notion Pages

To search a connected Notion workspace, the client emits a `tool_use` message:

```json
{
  "type": "tool_use",
  "id": "tu_1",
  "name": "notion_search",
  "input": {
    "query": "project roadmap",
    "pageSize": 5
  }
}

```

The server handler queries the Notion API via [`src/lib/notion/api.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/notion/api.ts) and returns structured results:

```json
{
  "type": "tool_result",
  "tool_use_id": "tu_1",
  "content": [
    {
      "title": "Q2 Roadmap",
      "id": "b7c1f2e8-...",
      "url": "https://www.notion.so/..."
    }
  ]
}

```

### Configuring Notion Authentication

Store a token via the settings API using cURL:

```bash
curl -X POST http://localhost:20128/api/settings/notion \
     -H "Content-Type: application/json" \
     -d '{"token":"token_v2=abcdef..."}'

```

Verify the connection:

```bash
curl http://localhost:20128/api/settings/notion

```

### Discovering and Scanning GitHub Skills

Search for reusable skill repositories:

```json
{
  "type": "tool_use",
  "id": "tu_2",
  "name": "omniroute_github_skills_search",
  "input": {
    "query": "eslint-config",
    "maxResults": 3
  }
}

```

Before installing, scan for safety issues:

```json
{
  "type": "tool_use",
  "id": "tu_3",
  "name": "omniroute_github_skills_scan",
  "input": {
    "repoUrl": "https://github.com/username/awesome-skill"
  }
}

```

If the scanner detects disallowed commands, it returns:

```json
{
  "type": "tool_result",
  "tool_use_id": "tu_3",
  "content": {
    "clean": false,
    "issues": ["found disallowed shell command"]
  }
}

```

## Summary

- **Centralized Registration**: The MCP server aggregates Notion and GitHub tools in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts), exposing them through a dynamic catalog at [`mcp-server/toolSearch/catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcp-server/toolSearch/catalog.ts).
- **Notion Security Model**: Uses a SQLite-backed `key_value` store ([`src/lib/db/notion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/notion.ts)) and REST configuration endpoints ([`src/app/api/settings/notion/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/settings/notion/route.ts)) to manage the `token_v2` cookie securely.
- **GitHub Skill Workflow**: Implements search-scan-install lifecycle tools in [`open-sse/mcp-server/tools/githubSkillTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/githubSkillTools.ts), leveraging public OAuth credentials from [`open-sse/utils/publicCreds.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/publicCreds.ts).
- **Scope Enforcement**: Both integrations validate permissions—`read:notion`/`write:notion` for Notion, `read:github`/`write:github` for GitHub—before executing handlers.

## Frequently Asked Questions

### How does OmniRoute store Notion authentication tokens?

OmniRoute persists the Notion `token_v2` cookie in a local SQLite database table named `key_value`, managed by [`src/lib/db/notion.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/notion.ts). The token is inserted or updated via SQL `INSERT OR REPLACE` operations, ensuring durable storage across server restarts while keeping credentials out of environment variables.

### What GitHub operations can the MCP server perform?

According to the OmniRoute source code, the server exposes three GitHub skill-collector tools: `omniroute_github_skills_search` for Marketplace queries, `omniroute_github_skills_scan` for static analysis of repository contents, and `omniroute_github_skills_install` for planning installation paths. These tools operate against public GitHub APIs using a resolved public OAuth client ID.

### Where are the MCP tool definitions located?

Tool definitions reside in service-specific TypeScript files under `open-sse/mcp-server/tools/`. Notion tools are defined in [`notionTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/notionTools.ts), while GitHub tools are defined in [`githubSkillTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/githubSkillTools.ts). Both files export arrays that the main server spreads into its runtime registry during initialization.

### How are permissions enforced on external service tools?

The MCP server implements scope-based authorization. Each tool descriptor includes required scopes—such as `read:notion` or `write:github`—which the authorization middleware validates against the request’s authentication token before invoking the handler. This prevents unauthorized write operations on external services.