Update diagrams and topology documentation

Author: danbarr

docs/toolhive/guides-cli/custom-permissions.md renamed to docs/toolhive/guides-cli/custom-permissions.mdx

@@ -6,6 +6,9 @@ description:
 sidebar_position: 50
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 ToolHive includes a permission system that lets you control an MCP server's
 access to your host's file system and to network resources. This is crucial for
 maintaining security and ensuring that MCP servers operate within defined
@@ -174,62 +177,123 @@ thv run --isolate-network --permission-profile </path/to/custom-profile.json> <s
 
 ## Network isolation
 
-To enforce the network access rules defined in your permission profile, you must
-use the `--isolate-network` flag when running the MCP server:
+To enforce the network access rules defined in your permission profile, use the
+`--isolate-network` flag when running the MCP server:
 
 ```bash
 thv run --isolate-network --permission-profile </path/to/custom-profile.json> <server-name>
 ```
 
-When network isolation is enabled, ToolHive creates a secure network
-architecture around your MCP server. Along with the main MCP server container,
-ToolHive launches:
+When you enable network isolation, ToolHive creates a secure network
+architecture around your MCP server. This architecture includes several
+components that work together to control network access.
+
+### Network architecture components
+
+Along with the main MCP server container, ToolHive launches additional
+containers to manage network traffic:
+
+- An egress proxy container that filters outgoing network traffic
+- A DNS container that provides controlled domain name resolution
+- An ingress proxy container that handles incoming requests (only for MCP
+  servers using SSE or Streamable HTTP transport; stdio MCP servers don't need
+  this since they don't expose ports)
+
+### Network topology
+
+ToolHive creates two separate networks in the container runtime:
+
+- A shared external network (`toolhive-external`) that connects to your host's
+  network
+- An internal network (`toolhive-<server-name>-internal`) for each MCP server
+  that isolates it from external access
+
+The MCP server container connects only to the internal network, while the proxy
+and DNS containers connect to both networks. This design ensures that all
+network traffic flows through controlled points, allowing ToolHive to enforce
+the access rules you specify in your permission profile.
 
-- **An egress Squid proxy container** that filters outgoing network traffic
-- **A dnsmasq container** that provides controlled DNS resolution
-- **An ingress Squid proxy container** that proxies incoming SSE requests from
-  the ToolHive proxy process (only for MCP servers using SSE transport; stdio
-  MCP servers don't need this since they don't expose ports)
+The following diagrams show how network traffic flows through the isolation
+architecture for different transport types:
 
-This multi-container setup ensures that all network traffic flows through
-controlled proxy points, allowing ToolHive to enforce the network access rules
-specified in your permission profile.
+<Tabs groupId='transport'>
+<TabItem value='stdio' label='Transport: Standard Input/Output (stdio)' default>
+
+For MCP servers using stdio transport, the ToolHive proxy process communicates
+directly with the MCP server container through standard input and output. All
+outbound network requests from the MCP server flow through the egress proxy and
+DNS containers:
 
 ```mermaid
-graph TB
-  subgraph "Host network"
-    Client[MCP client]
-    THVProxy[ToolHive SSE proxy]
-  end
-
-  subgraph "Docker networks"
-    subgraph "toolhive-external"
-      IngressProxy["Ingress proxy<br>(squid)"]
-    end
-
-    subgraph "toolhive-{name}-internal"
-      MCPServer[MCP server<br>container]
-      EgressProxy["Egress proxy<br>(squid)"]
-      DNSContainer["DNS container<br/>(dnsmasq)"]
-    end
-  end
-
-  External[External resources]
-
-  %% Traffic Flow
-  Client -->|SSE/HTTP request| THVProxy
-  THVProxy -->|Forward| IngressProxy
-  IngressProxy -->|Reverse proxy| MCPServer
-  MCPServer -->|Outbound requests| EgressProxy
-  EgressProxy -->|Filtered traffic| External
-  MCPServer -.->|DNS queries| DNSContainer
+architecture-beta
+    service mcp_client(server)[MCP client]
+    service toolhive_proxy(server)[ToolHive HTTP proxy process]
+
+    group container_runtime(server)[Container runtime]
+    group thv_internal(server)[Isolated network] in container_runtime
+    service egress(server)[Egress proxy container] in container_runtime
+    service mcp_server(server)[MCP server container] in thv_internal
+    service dns_container(server)[DNS container] in container_runtime
+
+    group external(internet)[External Resources]
+    service external_service(internet)[External service] in external
+    service external_dns(internet)[External DNS] in external
+
+    junction outbound in container_runtime
+
+    mcp_client:R --> L:toolhive_proxy
+    toolhive_proxy:R --> L:mcp_server
+    mcp_server:R -- L:outbound
+    egress:B <-- T:outbound
+    dns_container:T <-- B:outbound
+    egress:R --> L:external_service
+    dns_container:R --> L:external_dns
 ```
 
-:::note
+</TabItem>
+<TabItem value='sse' label='Transport: SSE or Streamable HTTP'>
+
+For MCP servers using SSE or Streamable HTTP transport, ToolHive includes an
+additional ingress proxy container. This proxy handles incoming HTTP requests
+and ensures the MCP server remains isolated from direct external access:
+
+```mermaid
+architecture-beta
+    service mcp_client(server)[MCP client]
+    service toolhive_proxy(server)[ToolHive HTTP proxy process]
+
+    group container_runtime[Container runtime]
+    group thv_internal[Isolated network] in container_runtime
+    service ingress(server)[Ingress proxy container] in container_runtime
+    service egress(server)[Egress proxy container] in container_runtime
+    service mcp_server(server)[MCP server container] in thv_internal
+    service dns_container(server)[DNS container] in container_runtime
+
+    group external[External resources]
+    service external_service(internet)[External service] in external
+    service external_dns(internet)[External DNS] in external
+
+    junction outbound in container_runtime
+
+    mcp_client:R --> L:toolhive_proxy
+    toolhive_proxy:R --> L:ingress
+    ingress:R --> L:mcp_server
+    mcp_server:R -- L:outbound
+    egress:B <-- T:outbound
+    dns_container:T <-- B:outbound
+    egress:R --> L:external_service
+    dns_container:R --> L:external_dns
+```
+
+</TabItem>
+</Tabs>
+
+:::important
 
-Network isolation currently supports only HTTP and HTTPS protocols. Other
-protocols like TCP sockets for database connections will not work with network
-isolation enabled.
+Network isolation supports HTTP and HTTPS protocols. If your MCP server needs to
+use other protocols (like direct TCP connections for database access), you'll
+need to run it without the `--isolate-network` flag and rely on the container's
+built-in isolation instead.
 
 :::
 

docs/toolhive/index.mdx

@@ -67,15 +67,11 @@ configurations.
 flowchart LR
   subgraph container["**Docker/Podman**"]
     direction LR
-    subgraph container1["Container"]
-        mcp1["MCP Server"]
-    end
-    subgraph container2["Container"]
-        mcp2["MCP Server"]
-    end
+      mcp1["MCP server<br>container"]
+      mcp2["MCP server<br>container"]
   end
     proxy1["SSE proxy"] -- stdio --> mcp1
-    proxy2["SSE proxy"] -- stdio --> mcp2
+    proxy2["SSE proxy"] -- SSE --> mcp2
     T["ToolHive CLI"] -- Socket API --> container
     C["Client"] -- HTTP/SSE --> proxy1 & proxy2
     T ~~~ C