How MCP Server Tools Integrate with Notion and GitHub in OmniRoute

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, the server aggregates core utilities, memory stores, and external service tools into a single array:

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), 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 module persists this sensitive value in a SQLite key_value table using INSERT OR REPLACE, ensuring the token survives server restarts:

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. 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. 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, 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 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:

• 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:

{
  "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 and returns structured results:

{
  "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:

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

Verify the connection:

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

Discovering and Scanning GitHub Skills

Search for reusable skill repositories:

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

Before installing, scan for safety issues:

{
  "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:

{
  "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, exposing them through a dynamic catalog at mcp-server/toolSearch/catalog.ts.
• Notion Security Model: Uses a SQLite-backed key_value store (src/lib/db/notion.ts) and REST configuration endpoints (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, leveraging public OAuth credentials from 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. 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, while GitHub tools are defined in 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.

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