mcp-bridge

Modular MCP platform with one public gateway, one central OAuth authorization service, and isolated private provider runtimes deployed as independently managed units.

Architecture

ChatGPT / MCP clients
   |                    |
   | MCP                | OAuth
   v                    v
gateway             authorization
  |                    |
  |                    +-- local users / OAuth / token state
  |
  |-- agent access ---> authorization (PostgreSQL + Valkey cache)
  |
  +-- /github/mcp   -------------> github
  +-- /gitlab/mcp   -------------> gitlab
  +-- /files/mcp    -------------> files
  +-- /web/mcp      -------------> web (curl + persistent Chromium)
  +-- /analysis/mcp -------------> analysis ---> ghidra (private)
  +-- /terminal/mcp -------------> terminal
  +-- /observability/mcp -------> observability (SigNoz + Coolify, read-only)

Gateway owns mcp.koba-nexus.ru. The authorization runtime is independently public at authorization.mcp.koba-nexus.ru. Provider runtimes remain private.

Related MCP server: production-grade-mcp-agentic-system

Public MCP surfaces

/mcp
/github/mcp
/gitlab/mcp
/files/mcp
/web/mcp
/analysis/mcp
/terminal/mcp
/observability/mcp

Native Ghidra is not a public MCP surface. Analysis is the external structured-analysis contract; Ghidra is an implementation backend.

Administration surfaces

https://admin.mcp.koba-nexus.ru/       -> admin-ui
https://api.mcp.koba-nexus.ru/v1/*    -> admin-api

Admin UI/Admin API are independent deployment units. Gateway does not proxy their HTTP or WebSocket routes.

OAuth and agent-access boundary

There is one local OAuth authorization server:

https://authorization.mcp.koba-nexus.ru

Every MCP endpoint under https://mcp.koba-nexus.ru is an independent RFC 8707 resource audience. The authorization-server issuer is separate from those MCP resource URLs. The authorization runtime owns local users, OAuth clients/codes/sessions, refresh tokens and the private ES256 signing key. Gateway owns public routing and verifies already-issued tokens with the public key/JWKS.

Agent access is a second authorization layer inside the same authorization service. In session_enforced mode each normal MCP call carries an agent session UID; sessions start read-only and may receive temporary/full access through administration approval. PostgreSQL is durable authority and Valkey is a read-through cache.

Provider accounts remain integrations and are not platform login identities.

Repository layout

services/
├── authorization/
│   └── access/
├── bridge/
├── common/
├── admin-api/
│   └── src/
│       └── admin_api/
└── modules/
    ├── github/
    ├── gitlab/
    ├── files/
    ├── web/
    ├── analysis/
    ├── ghidra/
    └── terminal/

Runtime and deployment isolation

Production is migrating from the legacy single Compose resource to independent Coolify Applications sharing one repository and multi-stage Dockerfile. admin-ui, admin-api and authorization already have separate Coolify resources; not all are healthy yet. The root Compose now owns only PostgreSQL and Valkey. Authorization's portable Dockerfile and Compose definitions live beside its Python package in services/authorization/; this staged pilot has not replaced the current Dockerfile Application.

Independent deployment units prevent a Git webhook for one provider from starting a Coolify deployment of the entire stack. Runtime correctness must not depend on selective-restart scripts. Cross-service requirements remain: GitHub and GitLab use Admin API for account resolution, while Analysis uses Ghidra. Gateway is deliberately not health-gated on provider availability, so one broken provider does not prevent the remaining MCP surfaces from starting and being used to repair the system. Backend MCP connections are lazy and reused: each public proxy keeps a small pool of persistent sessions instead of repeating MCP discovery/initialization for every tool call, while the root bridge keeps one persistent session per backend and caches backend tool catalogs for 30 seconds. bridge_tools(..., refresh=true) bypasses that catalog cache when an immediate schema refresh is required.

The multi-stage Dockerfile keeps rebuilds fast by installing locked dependencies before copying runtime-specific source trees, so unchanged stages reuse the local Docker cache.

Valkey is the private shared cache for account resolution and runtime/system settings. It is not a source of truth: Admin API remains authoritative, cache failures fall back to Admin API, and account/settings mutations invalidate or replace cached values. The production Valkey container is memory-only (no RDB/AOF volume and no published port). Resolved account entries may contain provider credentials, so they are short-lived and remain only inside the private Compose network and process/cache memory.

See docs/deployment.md for production deployment configuration.

Locked Python dependencies

Production and CI install dependencies from committed uv.lock:

uv sync --frozen --no-dev --no-install-project

This prevents clean deployments from resolving a different dependency graph.

Files

Files is the path-based file manager for the shared persistent /workspace filesystem. Terminal, Files, Web/curl and the Admin API see the same working files immediately. There is no separate content-addressed file store and no file_id storage contract.

Analysis

Analysis dynamically adapts the internal analysis backend catalog into the project terminology and validates/normalizes arguments before dispatch. Internal backend naming is not part of the external ChatGPT contract.

Admin API

Admin API owns provider accounts, encrypted credentials, invocation telemetry, settings, Files administration and the Admin API/realtime backend. GitHub, GitLab, SigNoz and Coolify can each have multiple named accounts. SigNoz API keys and Coolify API tokens are encrypted in Admin API; they are not deployment environment variables. Provider runtimes resolve the explicitly selected account_id/alias through the private Admin API rather than opening the Admin API database directly. Expensive workspace statistics and Reverse overview/coverage calculations are refreshed by background workers into persistent snapshots; the standalone frontend consumes the latest cached value with freshness metadata instead of performing long scans or analyses in the HTTP request path.

License

MIT

Terminal

Terminal is a dedicated non-root Linux development runtime exposed at /terminal/mcp. It provides persistent workspaces, bounded shell execution, durable long-running jobs, interactive PTY input/output and cursor-based incremental logs. Terminal, Files, Curl and Admin API file operations share the same mutable /workspace volume, so working files are immediately available by path without import/export copies. System toolchain packages are installed in the image; normal runtime commands execute as the unprivileged service user. Terminal command/stdin/output payloads are bounded or omitted in Admin API MCP-call history.

Web browser

The Web MCP combines structured curl operations with a persistent Playwright/Chromium browser profile. Browser cookies and local session state live in a dedicated persistent volume, while screenshots, uploads and downloads use the shared /workspace. Browser snapshots return bounded page text plus short-lived interactive element refs so agents can click and fill without serializing full page HTML into model context. Browser page content and filled values are omitted from Admin API audit payloads; tool/status metadata remains observable.

The standalone Admin UI uses the session-authenticated https://api.mcp.koba-nexus.ru/v1/browser/operator/ws Admin API surface for the same persistent Chromium profile. It shares tabs, input, agent/developer access controls, DevTools, reopen/cleanup operations and browser state with the Web runtime. Viewport changes use public PUT /v1/browser/viewport on the Admin API origin. The legacy HTML Browser Operator and ticket-authenticated /admin/browser/ws surface have been removed.

The Web surface also mounts Google's official chrome-devtools-mcp server (pinned to 1.10.1) under the devtools_ namespace instead of reimplementing Chrome debugging RPCs. It connects only to the same loopback CDP endpoint used by the persistent browser. Agent Developer access is a separate browser-wide privilege and defaults to off; privileged calls require both Agents: On and Developer: On. Turning either switch off disconnects the privileged stdio upstream. Full Developer mode intentionally sees all browser targets rather than honoring per-tab basic-browser locks. The operator UI persists the Developer switch in the browser policy; a fresh profile starts with Developer access off.

The upstream exposes its native console, network, JavaScript evaluation, DOM/CSS, performance, memory and extension tools without Koba schema translation. Extension/source filesystem access is restricted to /workspace; file navigations and CrUX URL uploads are disabled. DevTools MCP arguments and results are omitted from Admin API audit payloads because they may contain cookies, authorization headers, JavaScript, request bodies or authenticated page data. Tool name, status, duration and traces remain observable. The runtime uses normal Chromium capabilities; it does not add fingerprint spoofing or site-control bypass logic.

The managed Chromium keeps its existing browser_* and privileged devtools_* surfaces. An operator may additionally configure an official Microsoft Playwright MCP server from Admin → Settings → Browser. Endpoint, per-call timeout, Chrome profile, explicit/idle disconnect policy and Playwright Extension token are stored as runtime policy in Admin API/PostgreSQL rather than container environment variables. The token is encrypted at rest and public settings expose only whether it is configured; a service-authenticated browser-launcher policy endpoint may resolve the secret when a local Windows launcher needs to populate PLAYWRIGHT_MCP_EXTENSION_TOKEN.

External Playwright tools are mounted under the external_* namespace and reuse one persistent upstream MCP session, so one approved browser selection remains active across tool calls until an explicit disconnect, process loss, policy change, or optional idle timeout. The external browser path is independent from the managed Chromium and never redirects the managed devtools_* backend.

OAuth sessions

The authorization runtime stores local OAuth users, clients, authorization codes, OAuth sessions and refresh-token state in PostgreSQL. Refresh tokens rotate on use and access tokens are short-lived ES256 JWTs signed only by the authorization runtime; gateway validates them locally with the public key. Provider integrations such as GitHub and GitLab do not participate in platform login or token refresh.

Observability

Observability is one unified read-only MCP surface at /observability/mcp. Admin API keeps SigNoz and Coolify connections as separate account types because their credentials and APIs are different, but ChatGPT connects to only this one surface. observability_sources lists both provider types and their aliases; data tools require an explicit account selector.

SigNoz-backed tools provide runtime logs, traces, metrics/query access, service discovery and field discovery. Coolify-backed tools provide application and deployment state. Coolify runtime logs, environment variables, secrets and all deploy/restart/mutation operations are deliberately absent; runtime diagnostics belong to the SigNoz side of the same Observability interface.

Hot-path telemetry distinguishes cache/Admin API access, backend MCP session reuse, provider HTTP latency and connection-pool wait, and Admin API repository operations. Admin API audit delivery is batched through a bounded in-memory queue: each MCP call remains an individual audit record and metric event, while short batches share one internal HTTP request and one SQL transaction. Sensitive arguments, credentials, authorization headers, full request URLs and cache keys are not exported as span attributes.