Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/toolhive/guides-k8s/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,18 +36,18 @@ The operator introduces a new Custom Resource Definition (CRD) called
flowchart TB
subgraph K8s["<h3>Kubernetes cluster</h3>"]
subgraph K8s1["**Deployment**"]
Svc1["SSE Proxy<br>Service"] -- http/sse --> Proxy1["SSE Proxy<br>Pod"] -- stdio or http/sse --> MCP1["MCP Server<br>Pod"]
Svc1["HTTP Proxy<br>Service"] -- http --> Proxy1["HTTP Proxy<br>Pod"] -- stdio or http --> MCP1["MCP Server<br>Pod"]
Proxy1 -.->|creates| MCP1
end
subgraph K8s2["**Deployment**"]
Svc2["SSE Proxy<br>Service"] -- http/sse --> Proxy2["SSE Proxy<br>Pod"] -- stdio or http/sse --> MCP2["MCP Server<br>Pod"]
Svc2["HTTP Proxy<br>Service"] -- http --> Proxy2["HTTP Proxy<br>Pod"] -- stdio or http --> MCP2["MCP Server<br>Pod"]
Proxy2 -.->|creates| MCP2
end
Ingress["Ingress"] -- http/sse --> Svc1 & Svc2
Ingress["Ingress"] -- http --> Svc1 & Svc2
Operator["ToolHive<br>Operator"] -.->|creates| K8s1 & K8s2
end

Client["MCP Client<br>[ex: Copilot]"] -- http/sse --> Ingress
Client["MCP Client<br>[ex: Copilot]"] -- http --> Ingress
```

## Installation
Expand Down
28 changes: 14 additions & 14 deletions docs/toolhive/guides-k8s/run-mcp-k8s.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,12 +65,12 @@ flowchart LR
Proxy -->|Attaches/STDIO| MCP
```

### SSE transport flow
### Streamable HTTP and SSE transport flow

For MCP servers using Server-Sent Events (SSE) transport, the proxy creates both
a pod and a headless service. This allows direct HTTP/SSE communication between
the proxy and MCP server while maintaining network isolation and service
discovery.
For MCP servers using Server-Sent Events (SSE) or Stremable HTTP transport, the
proxy creates both a pod and a headless service. This allows direct HTTP/SSE or
HTTP/Streamable HTTP communication between the proxy and MCP server while
maintaining network isolation and service discovery.

```mermaid
flowchart LR
Expand All @@ -87,8 +87,8 @@ flowchart LR
MCPPod["POD: MCP Server"]
end

Client["Client"] -->|HTTP/SSE| Proxy
Proxy -->|HTTP/SSE| MCP
Client["Client"] -->|HTTP| Proxy
Proxy -->|HTTP| MCP
MCPService --> MCPPod
```

Expand Down Expand Up @@ -117,7 +117,7 @@ metadata:
namespace: my-namespace # Update with your namespace
spec:
image: ghcr.io/stackloklabs/osv-mcp/server
transport: sse
transport: streamable-http
port: 8080
permissionProfile:
type: builtin
Expand Down Expand Up @@ -153,8 +153,9 @@ When you apply an `MCPServer` resource, here's what happens:
service to handle client connections
4. The proxy creates the actual `MCPServer` pod containing your specified
container image
5. For STDIO transport, the proxy attaches directly to the pod; for SSE
transport, a headless service is created for direct pod communication
5. For STDIO transport, the proxy attaches directly to the pod; for SSE and
Streamable HTTP transport, a headless service is created for direct pod
communication
6. Clients can now connect through the service → proxy → MCP server chain to use
the tools and resources (note: external clients will need an ingress
controller or similar mechanism to access the service from outside the
Expand Down Expand Up @@ -217,9 +218,8 @@ metadata:
namespace: development # Can be any namespace
spec:
image: ghcr.io/stackloklabs/gofetch/server
transport: sse
transport: streamable-http
port: 8080
targetPort: 8080
permissionProfile:
type: builtin
name: network
Expand Down Expand Up @@ -474,8 +474,8 @@ Common causes include:
selectors
- **Port configuration**: Verify the `port` field matches the MCP server's
listening port
- **Transport mismatch**: Ensure the `transport` field (stdio/sse) matches the
MCP server's capabilities
- **Transport mismatch**: Ensure the `transport` field
(stdio/sse/streamable-http) matches the MCP server's capabilities
- **Network policies**: Check if network policies are blocking communication

</details>
Expand Down