mcp-catalogue

mcp-catalogue

Browse-first MCP middleware — an LLM-friendly catalogue for discovering and invoking MCP tools across multiple services.

AI agents (Open WebUI, n8n, etc.) use this as a single MCP endpoint to browse, inspect, and call tools from many upstream MCP servers — without flooding their context with every tool schema upfront.

How It Works

Instead of connecting every MCP server directly (and loading all their tool schemas at session start), agents connect to one catalogue server and discover tools on demand:

browse_services              → [{id: "todoist", name: "Todoist"}, {id: "outlook", ...}]
browse_tools("todoist")      → ["todoist__get-task", "todoist__create-task", ...]
get_schemas(["todoist__get-task"])  → [full input schema]
call_tool("todoist__get-task", {id: "123"}) → result

Quick Start

Prerequisites

• Node.js 22+
• An MCP server to point it at (or use the included smoke test)

Install & Run

# Install dependencies
npm install

# Copy a config (or create your own)
cp mcp-catalogue.dev.yaml mcp-catalogue.yaml

# Start in dev mode (with hot reload)
npm run dev

# Or with a custom config path and verbose logging
npx tsx src/index.ts --config ./mcp-catalogue.dev.yaml --verbose

Verify It's Running

# Health check
curl http://localhost:8050/health

# Quick smoke test
node smoke-test.mjs

Configuration

Create a mcp-catalogue.yaml file:

port: 8050
auth:
  enabled: false # Set to true and provide a token in production
  token: ""
  allowedOrigins: # Optional — restrict CORS to these origins when auth is on
    - https://openwebui.local

connectors:
  httpReuseIdleTimeoutSeconds: 300 # Reap idle upstream HTTP sessions after N seconds

sources:
  - id: todoist
    name: Todoist
    description: Task and project management
    transport: http
    url: http://todoist-mcp:8081/mcp
    filter: ["*"] # Glob patterns — only index matching tools

  - id: outlook
    name: Outlook
    description: Email and calendar
    transport: stdio
    command: npx
    args: ["-y", "@softeria/ms-365-mcp-server"]
    env:
      API_KEY: "your-key"

Config Reference

Sample configs are included:

• mcp-catalogue.dev.yaml — LAN IPs for local development
• mcp-catalogue.prod.yaml — container-internal DNS for Docker

Docker

# Build
npm run docker:build

# Run
docker run -d \
  --name mcp-catalogue \
  -p 8050:8050 \
  -v ./mcp-catalogue.yaml:/app/mcp-catalogue.yaml \
  -e MCP_CATALOGUE_AUTH_TOKEN=your-token \
  mcp-catalogue

Or use the provided Dockerfile directly:

docker build -t mcp-catalogue .

MCP Tools

The catalogue exposes these tools to connected AI agents:

Architecture

AI Agent ──Streamable HTTP──▶ mcp-catalogue ──HTTP/stdio──▶ todoist, outlook, ...
                                  │
                              In-memory index
                              Session management

• Transport: MCP Streamable HTTP (2025-11-05)
• Auth: Optional bearer token, with optional CORS origin allowlist
• Health: GET /health endpoint for monitoring (Uptime Kuma, etc.)
• HTTP connection reuse: keep-alive sessions per source, reaped after an idle timeout

Project Structure

src/
  index.ts              Entry point with CLI args
  config.ts             YAML loader with Zod validation
  types.ts              Shared types and interfaces
  logger.ts             Structured logger
  namespace.ts          Tool name namespacing (<sourceId>__<toolName>)
  indexer.ts            Startup index — fetches tools/list from all sources
  catalogue-server.ts   MCP server — tool definitions and request handling
  sources/
    http-source.ts      HTTP transport client (Streamable HTTP)
    stdio-source.ts     Stdio transport client (subprocess, JSON-RPC)

Scripts