From 0427d7dc1aee69464c2541bca2e4576880f40dc7 Mon Sep 17 00:00:00 2001 From: Michal Date: Fri, 27 Feb 2026 17:12:29 +0000 Subject: [PATCH] fix: correct architecture diagram in README MCP server containers are managed by and proxied through mcpd, not directly accessible. Updated diagram to show containers nested inside mcpd boundary with explanation. Co-Authored-By: Claude Opus 4.6 --- README.md | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9643fa2..36c0809 100644 --- a/README.md +++ b/README.md @@ -282,36 +282,38 @@ mcpctl console --inspect ## Architecture ``` - ┌─────────────────────────────────────────┐ - │ mcpd (daemon) │ - │ │ - │ REST API (/api/v1/*) │ - │ PostgreSQL (Prisma ORM) │ - │ Docker/Podman container management │ - │ Health probes (STDIO, SSE, HTTP) │ - │ RBAC enforcement │ - └──────────────┬──────────────────────────┘ - │ HTTP - │ -┌──────────────┐ STDIO ┌──────────────┴──────────────────────────┐ -│ Claude Code │◄─────────►│ mcplocal (proxy) │ -│ │ │ │ +┌──────────────┐ ┌─────────────────────────────────────────┐ +│ Claude Code │ STDIO │ mcplocal (proxy) │ +│ │◄─────────►│ │ │ (or any MCP │ │ Namespace-merging MCP proxy │ │ client) │ │ Gated sessions + prompt delivery │ │ │ │ Per-project endpoints │ └──────────────┘ │ Traffic inspection │ └──────────────┬──────────────────────────┘ - │ STDIO/SSE/HTTP + │ HTTP (REST + MCP proxy) │ ┌──────────────┴──────────────────────────┐ - │ MCP Server Containers │ + │ mcpd (daemon) │ │ │ - │ grafana/ home-assistant/ docmost/ │ - │ (tools are namespaced by server name) │ + │ REST API (/api/v1/*) │ + │ MCP proxy (routes tool calls) │ + │ PostgreSQL (Prisma ORM) │ + │ Docker/Podman container management │ + │ Health probes (STDIO, SSE, HTTP) │ + │ RBAC enforcement │ + │ │ + │ ┌───────────────────────────────────┐ │ + │ │ MCP Server Containers │ │ + │ │ │ │ + │ │ grafana/ home-assistant/ ... │ │ + │ │ (managed + proxied by mcpd) │ │ + │ └───────────────────────────────────┘ │ └─────────────────────────────────────────┘ ``` -**Tool namespacing**: When Claude connects to a project with servers `grafana` and `slack`, it sees tools like `grafana/search_dashboards` and `slack/send_message`. The proxy routes each call to the correct upstream server. +Clients never connect to MCP server containers directly — all tool calls go through mcplocal → mcpd, which proxies them to the right container via STDIO/SSE/HTTP. This keeps containers unexposed and lets mcpd enforce RBAC and health checks. + +**Tool namespacing**: When Claude connects to a project with servers `grafana` and `slack`, it sees tools like `grafana/search_dashboards` and `slack/send_message`. mcplocal routes each call through mcpd to the correct upstream server. ## Project Structure