Skip to content

Add K8s client connectivity guide #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
danbarr merged 5 commits into from
Dec 4, 2025
Merged

Add K8s client connectivity guide #310

danbarr merged 5 commits into from
Dec 4, 2025

Conversation

@danbarr
Copy link
Collaborator

@danbarr danbarr commented Nov 21, 2025

Description

Adds a guide detailing options for connecting clients to MCP servers running in Kubernetes:

  • External clients via Ingress
  • External clients via Gateway API
  • Clients within the same cluster

Related issues/PRs

Closes #307

Merge checklist

Content

  • New pages include a frontmatter section with title and description at a minimum
  • Sidebar navigation (sidebars.ts) updated for added, deleted, reordered, or renamed files
  • (N/A) Redirects added to vercel.json for moved, renamed, or deleted pages (i.e., if the URL slug changed)

Reviews

  • Content has been reviewed for technical accuracy
  • Content has been reviewed for spelling, grammar, and style

Copilot AI review requested due to automatic review settings November 21, 2025 03:44
@vercel
Copy link

vercel bot commented Nov 21, 2025 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
docs-website Ready Ready Preview Comment Dec 3, 2025 10:33pm

Copilot finished reviewing on behalf of danbarr November 21, 2025 03:46
Copilot AI reviewed Nov 21, 2025
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds a comprehensive guide for connecting clients to MCP servers running in Kubernetes, covering both external connectivity via Ingress/Gateway API and internal cluster connectivity. The guide helps users expose MCP servers securely and establish proper connection patterns for different scenarios.

  • Adds detailed documentation on connecting external and internal clients to Kubernetes-hosted MCP servers
  • Provides practical examples for Ingress, Gateway API, and in-cluster service discovery patterns
  • Includes extensive troubleshooting section covering common connectivity issues

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
docs/toolhive/guides-k8s/connect-clients.mdx New comprehensive guide explaining client connectivity options for MCP servers in Kubernetes, including external access via Ingress/Gateway API and internal cluster access patterns
sidebars.ts Adds the new connect-clients guide to the Kubernetes guides section in the appropriate position between run-mcp-k8s and remote-mcp-proxy
docs/toolhive/guides-k8s/intro.mdx Adds reference to the new connectivity guide explaining how to expose MCP servers and connect clients
docs/toolhive/guides-k8s/run-mcp-k8s.mdx Updates "Next steps" section to reference the new connectivity guide with more detailed context about connection options
docs/toolhive/tutorials/k8s-ingress-ngrok.mdx Adds tip box referencing the new general connectivity guide for broader context beyond the ngrok-specific tutorial

@danbarr
Copy link
Collaborator Author

danbarr commented Nov 21, 2025

Setting to draft for now while I validate auth interoperability (esp. with rewrites)

@danbarr danbarr marked this pull request as draft November 21, 2025 22:23
@danbarr danbarr force-pushed the add-k8s-connecting-guide branch from 59b0ba7 to d784cbc Compare November 27, 2025 04:16
@danbarr danbarr marked this pull request as ready for review November 27, 2025 04:20
@danbarr danbarr enabled auto-merge (squash) November 27, 2025 04:21
@danbarr danbarr requested a review from jhrozek November 27, 2025 04:28
@danbarr
Add K8s client connectivity guide
9405c5b 
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
@danbarr
Add path-based routing
c2fdd9d 
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
@danbarr
Add auth configs for path-based routing
c9b9099 
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
@danbarr
Streamline ngrok tutorial and add auth addendum
523a279 
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
@danbarr danbarr force-pushed the add-k8s-connecting-guide branch from a9b7e79 to 523a279 Compare November 28, 2025 02:55
jhrozek
jhrozek reviewed Dec 3, 2025
View reviewed changes
Copy link
Contributor

@jhrozek jhrozek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this comprehensive guide! I have a few questions about some details.

@danbarr
Apply review suggestions
302fa76 
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
@jhrozek
Copy link
Contributor

jhrozek commented Dec 4, 2025

Question about Gateway API version: The latest Gateway API version is v1.4.1, but line 88 references v1.3.0. Is that intentional for compatibility reasons, or should we update to the latest version?

@danbarr
Copy link
Collaborator Author

danbarr commented Dec 4, 2025

Question about Gateway API version: The latest Gateway API version is v1.4.1, but line 88 references v1.3.0. Is that intentional for compatibility reasons, or should we update to the latest version?

That was copied from ngrok's operator install docs. I'm inclined to leave it in the tutorial for now since they still reference that version.

Eventually I want to explore some Renovate customization to look into the docs and potentially identify/bump versioned references like these.

jhrozek
jhrozek approved these changes Dec 4, 2025
View reviewed changes
Copy link
Contributor

@jhrozek jhrozek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentation Verification Complete

I tested the documentation in a live Kubernetes cluster with the ToolHive operator and ngrok Gateway API. All test scenarios passed.

Test Environment

  • Kubernetes cluster with ToolHive operator
  • ngrok Gateway API controller
  • MCP servers: fetch, osv, mkp (with OAuth)
  • Okta as OIDC provider

Tests Performed

Gateway API (External Connectivity)

  • Host-based routing (single MCP server) - PASS
  • Path-based routing with URL rewrite (multiple MCP servers) - PASS
  • Path-based routing with OAuth (.well-known endpoint discovery) - PASS

Internal Connectivity

  • Service DNS resolution (same namespace - short name) - PASS
  • Service DNS resolution (cross-namespace - full FQDN) - PASS
  • Port-forward local testing - PASS

CLI/API Testing

  • thv mcp list tools command - PASS
  • curl JSON-RPC requests - PASS
  • OAuth token authentication flow - PASS

Troubleshooting Commands

  • kubectl get httproute status verification - PASS
  • DNS resolution test from pod (nslookup) - PASS
  • Connectivity test from pod (curl) - PASS

Notes

  • All YAML examples are syntactically correct and work as documented
  • The ngrok-specific replacePrefixMatch: '' behavior is correctly documented in the ngrok tutorial
  • OAuth .well-known endpoint routing works correctly with path-based routing

@danbarr danbarr merged commit e007e2d into main Dec 4, 2025
5 checks passed
@danbarr danbarr deleted the add-k8s-connecting-guide branch December 4, 2025 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@jhrozek jhrozek jhrozek approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add Kubernetes guide for connecting clients

3 participants

@danbarr @jhrozek