ITWorx MCP Hub

A self-hosted governance platform for connecting AI clients to approved tools and knowledge. The Hub scopes capabilities by project, environment and client identity, while retaining policy decisions and audit attribution.

What it provides

A management UI for projects, readiness, policies, connector health and audit history.
An MCP dataplane and router with authenticated, bounded tool discovery and invocation.
Target-specific integrations for knowledge, Gitea, ProjectBrain, AppOps and infrastructure.
OIDC client onboarding and separately scoped service-to-service credentials.
Explicit deny-by-default authorization inside sensitive connectors.
PostgreSQL persistence, migrations, workers and recovery tooling.

The gateway, API and normal connectors never receive a Docker socket. Only the dedicated read broker may access it, through its purpose-built read-only interface. There is no general shell, unrestricted SQL or arbitrary filesystem tool.

Architecture

flowchart LR
  Client[MCP client] --> Router[Authenticated dataplane]
  UI[Management UI] --> API[Control API]
  API --> DB[(PostgreSQL)]
  Router --> Policy[Scoped connector authorization]
  Policy --> Tools[Approved tools and knowledge]

apps/web contains the React management UI; services contains runtime services; connectors supplies integrations; packages holds shared policy/contracts. Compose definitions, image build contexts and database migrations live in infrastructure.

Deployment

Requirements: Docker with Compose, Python 3.13, Node.js 24 and pnpm 10.33. The production stack is intentionally configuration-driven and has no universal one-command public demo.

Copy infrastructure/compose/.env.example to an untracked .env in that directory.
Replace every REPLACE_* input: dedicated host paths, bind addresses, OIDC issuer/client settings, project/resource bindings and immutable owned image references.
Build the owned images from the supplied contexts and use immutable image digests. Provision the named secret files outside Git according to Secret storage.
Review Compose requirements, configure TLS routing and run migrations before starting the full stack.
Validate authentication, connector reachability and denied operations before onboarding clients.

cd infrastructure/compose
docker compose --env-file .env config --quiet
# Start only after required inputs, secret files and image references are reviewed.
docker compose --env-file .env up -d

The public snapshot omits the owner's catalog project, workspace and resource bindings. Create your own scoped bindings before catalog reconciliation; no production project access is preconfigured.

External OIDC, registries and connector services are operator-supplied dependencies. Do not substitute real production credentials into examples. Optional connectors can remain unconfigured. The development override is an engineering environment, not an internet-ready deployment.

Client onboarding and security

See Client onboarding and Security invariants. A visible tool is not authorization to use it: project, environment, resource identity and caller privileges are checked independently. Report issues privately according to SECURITY.md.

Development

Python dependencies are locked by uv.lock; Node workspaces are locked by pnpm-lock.yaml. Tests cover authorization, contracts and runtime behavior. Canonical python scripts/verify.py additionally checks private design/evidence metadata; that complete archival gate belongs to the private repository. For public source development, install locked dependencies and run the relevant unit/integration tests and apps/web build. Integration/browser tests require their documented external services.

Public source and license

ITWorx_MCP_Hub-Public is automatically exported from canonical private main. It contains reviewed source, tests and reusable deployment definitions, with example domains and paths substituted for operational topology. Private Git history, live inventories, evidence, internal Actions and production-specific delivery overrides are excluded.

The project remains proprietary under LICENSE.md. Public visibility grants no additional reuse rights; third-party dependencies retain their licenses.

4.4 KiB Raw Blame History