Add proposal for operator registry integration via Gateway API #2591

JAORMX · 2025-11-14T17:56:56Z

This proposal enables automatic MCP registry population based on Gateway API resources, making it easy for administrators to expose and discover MCP servers.

Summary

The operator will watch Gateway API HTTPRoute resources (annotated with toolhive.stacklok.dev/registry-export: "true") to discover which MCP servers are externally accessible. It constructs the full endpoint URL by traversing to the parent Gateway resource and creates registry entries in the upstream MCP Registry format.

Key Features

Gateway API integration: Watches HTTPRoute resources for annotation-based discovery
Explicit opt-in: Only HTTPRoutes with registry-export annotation are discovered
Annotation fallback: Direct URL annotation for non-Gateway API users
Rich metadata: Tier, tools, and tags via annotations
Upstream format: Uses modelcontextprotocol/registry format with ToolHive extensions
Event-based tracking: Kubernetes Events instead of status field bloat

Two Discovery Methods

Primary (Gateway API): Annotate HTTPRoute → operator discovers endpoint
Fallback (Direct URL): Annotate MCP resource → operator uses explicit URL

Annotations

Discovery control:

toolhive.stacklok.dev/registry-export: Enable discovery
toolhive.stacklok.dev/registry-url: Direct URL (fallback)
toolhive.stacklok.dev/registry-name: Override entry name

Metadata:

toolhive.stacklok.dev/registry-tier: "Official" | "Community" | "Partner"
toolhive.stacklok.dev/registry-tools: Comma-separated tool names
toolhive.stacklok.dev/registry-tags: Comma-separated tags
toolhive.stacklok.dev/registry-description: Human-readable description

Design Decisions

Separation of concerns: Ingress config stays separate from MCP resources (follows ToolHive design principles)
Explicit control: Administrators choose what to expose via annotations
Progressive rollout: Create HTTPRoute, test it, then add annotation when ready
Standard format: Uses upstream MCP Registry format for compatibility

Implementation Phases

Phase 1: Direct URL annotation discovery
Phase 2: Gateway API HTTPRoute discovery
Phase 3: Production hardening (cross-namespace validation, cleanup)

🤖 Generated with Claude Code

codecov · 2025-11-17T12:24:52Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 56.45%. Comparing base (55ee37d) to head (50be7c6).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2591   +/-   ##
=======================================
  Coverage   56.45%   56.45%           
=======================================
  Files         319      319           
  Lines       30882    30882           
=======================================
  Hits        17433    17433           
  Misses      11950    11950           
  Partials     1499     1499

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

rdimitrov

Overall LGTM but let's make sure we get this reviewed by the others too before going through with the implementation 👍

rdimitrov · 2025-11-19T22:51:16Z

docs/proposals/THV-2591-operator-registry-integration-via-gateway-api.md

+        }
+      },
+      "_meta": {
+        "io.modelcontextprotocol.registry/official": {


That part is probably obsolete as this metadata is supposed to come if we were to get an MCP server from the upstream registry.

dmartinol

nice proposal, reminds me a full MCP gateway now 🤔

dmartinol · 2025-11-20T08:28:22Z

docs/proposals/THV-2591-operator-registry-integration-via-gateway-api.md

+
+**Metadata Annotations** (on HTTPRoute or MCP resource):
+4. **`toolhive.stacklok.dev/registry-tier`**: Server classification ("Official", "Community", "Partner")
+5. **`toolhive.stacklok.dev/registry-tools`**: Comma-separated list of tool names (e.g., "create_pr,merge_pr,list_issues")


why should we repeat the tools and tags if the registry already advertise them in the registered server? (e.g. the server with OCI package should be already there, right?)
maybe the annotations should connect the MCPServer to the registered server package with annotations sharing the name and version of the server?
BTW: of course also possible tool configs should be taken into account for filtering and renaming

Also, please review the possible overlaps with #2105
e.g., how many remotes are we going to advertise in the registry for a single MCPServer? I guess 1 for in-cluster consumers and, optionally, 1 for external consumers (this proposal)

I removed the tools and tags from the proposal.

ChrisJBurns · 2025-11-20T15:21:20Z

docs/proposals/THV-2591-operator-registry-integration-via-gateway-api.md

+2. Extracts the base MCP path from HTTPRoute rules
+3. Traverses to parent Gateway resource(s) to get external hostname/IP
+4. Constructs the full external endpoint URL
+5. Creates an entry in the MCPRegistry pointing to this external endpoint


I think this is the detail we need to hash out. For the fallback approach, I think things are slightly simpler because the time which the Operator creates the MCP server, it is aware of what the URL is because its provided as an annotation. This way, the Operator can send a single request to the registry server, publishing information about the newly deployed and running MCP server, including it's externally accessible URL.

With the primary approach, I'm not sure of the sequence flow. The Operator will publish information to the registry server when it creates the MCP server, but the publishing of information around the externally accessible URL may not be known at the time because the Gateway API resources may be created by the user later on. This will result in a subsequent request to the registry server that denotes that there is now an externally accessible URL and to save it in the database.

I'm not saying this is a problem, I just think we need to iron out the specifics in the lower levels of the requests that will be sent in the scenarios. Possibly a sequence diagram will help here? This will also need to be factored into the registry server API design that @blkt has been steering so that if we do want to allow for the subsequent requests, what does the API look like for that.

ChrisJBurns · 2025-11-20T15:29:10Z

docs/proposals/THV-2591-operator-registry-integration-via-gateway-api.md

+
+1. Detects the annotated HTTPRoute and validates it's accepted by the Gateway controller
+2. Extracts the base MCP path from HTTPRoute rules
+3. Traverses to parent Gateway resource(s) to get external hostname/IP


Do we think users will be ok with the Operator being able to read the Gateway API resources and traversing them to build a URL? For MCP related resources its perhaps not a problem, but for others, it seems a bit "grabby"

Do we need to traverse to the Gateway resource to get hostname? The hostnames are provided in the HTTPRoute right? Perhaps we don't need to go any further to avoid grabbing what we don't need (see point 1). Or are you saying that we may need to traverse because the hosts are optional in the HTTPRoute and can contain wildcards?

yes, I think so. We can make this optional via a flag as @dmartinol suggested.

yes we do, I don't see any other way to get a canonical name given the optionality of them.

For 1), I'm wondering how we feature flag the RBAC roles that the Operator has. Currently they are auto-generated using kubebuilder, if we have any Helm conditionals they will be overwritten.

docs/proposals/THV-2591-operator-registry-integration-via-gateway-api.md

JAORMX · 2025-11-24T14:11:00Z

@dmartinol I mean the Gateway API from Kubernetes. The idea is to get MCPServers auto-enrolled in the registry using HTTPRoutes.

dmartinol · 2025-11-26T13:53:18Z

@dmartinol I mean the Gateway API from Kubernetes. The idea is to get MCPServers auto-enrolled in the registry using HTTPRoutes.

Auto-enrollment was also planned by #2105

dmartinol · 2025-11-26T13:53:48Z

Finally, please consider that this feature should be disabled accordingly to #2564

JAORMX · 2025-11-26T16:35:02Z

@dmartinol I mean the Gateway API from Kubernetes. The idea is to get MCPServers auto-enrolled in the registry using HTTPRoutes.

Auto-enrollment was also planned by #2105

Right, this basically provides a way of implementing that which sysadmins to choose what to expose and what not.

JAORMX · 2025-11-26T16:35:30Z

Finally, please consider that this feature should be disabled accordingly to #2564

Right, that makes sense. Though this doesn't really introduce new CRDs

This proposal enables the ToolHive Kubernetes operator to automatically populate the MCP registry with externally accessible endpoints for MCPServer, MCPRemoteProxy, and VirtualMCPServer resources. Key features: - Gateway API HTTPRoute annotation-based discovery (primary approach) - Direct URL annotation fallback (for non-Gateway API users) - Explicit opt-in model for administrator control - Upstream MCP registry format with ToolHive publisher extensions - Kubernetes Events for discovery tracking The approach maintains clear separation between ingress configuration and MCP resource definitions, following ToolHive's design principles. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

…ration

dmartinol · 2025-11-27T11:05:35Z

Finally, please consider that this feature should be disabled accordingly to #2564

Right, that makes sense. Though this doesn't really introduce new CRDs

I see, but the auto-registration feature must be disabled if the registry is not enabled

Implements Phase 1 of operator registry export (PR #2591). The controller watches MCPServer, MCPRemoteProxy, and VirtualMCPServer resources for registry export annotations and aggregates them into a ConfigMap per namespace in the upstream MCP registry format. Key features: - Annotation-based export using `toolhive.stacklok.dev/registry-url` - Per-namespace ConfigMap with `{namespace}-registry-export` naming - Feature toggle via Helm value `operator.features.registryExport` or env var `ENABLE_REGISTRY_EXPORT` (disabled by default) - Stable checksums computed only on server entries (not timestamps) - Deterministic output with sorted entries - Efficient ConfigMap watches using label predicate filter 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

blkt · 2025-11-28T10:51:00Z

docs/proposals/THV-2591-operator-registry-integration-via-gateway-api.md

+**For servers FROM a known registry:**
+- The operator looks up the image reference in configured MCPRegistry sources
+- If found, it adds a `remotes` entry to the existing server entry
+- Metadata (name, description, version) comes from the source registry


concern: I believe we need to clarify the assumption underlying this scenario.

This assumes that

it is possible to find out whether an MCP server comes from a known Registry

it is possible to update an existing entry

Point 1. might be complicated but achievable, but point 2. is not currently possible.

Regarding point 2., as of now we implement Upstream API in ToolHive Registry Server in pretty strictly and only add support for deleting MCP server entries (which is in Upstream Registry API spec but they do not support it). This entails that updates can only be implemented as delete-create cycles. This might not be ideal but we might live with it for now.

Regarding point 1., it is not clear to me how this can be achieved, could you clarify? It would be great if you could do it here, meanwhile I'll have a look at #2792.

…ration

JAORMX force-pushed the proposal/operator-registry-gateway-api-integration branch from 364577d to 7bf59f7 Compare November 14, 2025 17:57

rdimitrov reviewed Nov 19, 2025

View reviewed changes

rdimitrov requested review from ChrisJBurns, blkt, dmartinol and dmjb November 19, 2025 23:01

dmartinol reviewed Nov 20, 2025

View reviewed changes

ChrisJBurns reviewed Nov 20, 2025

View reviewed changes

JAORMX force-pushed the proposal/operator-registry-gateway-api-integration branch from 7bf59f7 to 339d165 Compare November 26, 2025 14:19

github-actions bot added the size/M Medium PR: 300-599 lines changed label Nov 26, 2025

JAORMX force-pushed the proposal/operator-registry-gateway-api-integration branch from 339d165 to c99a64a Compare November 26, 2025 17:02

github-actions bot added size/M Medium PR: 300-599 lines changed and removed size/M Medium PR: 300-599 lines changed labels Nov 26, 2025

Merge branch 'main' into proposal/operator-registry-gateway-api-integ…

8dce5b2

…ration

github-actions bot added size/M Medium PR: 300-599 lines changed and removed size/M Medium PR: 300-599 lines changed labels Nov 26, 2025

JAORMX mentioned this pull request Nov 28, 2025

Add registry export controller for automatic MCP resource discovery #2792

Open

4 tasks

blkt reviewed Nov 28, 2025

View reviewed changes

Merge branch 'main' into proposal/operator-registry-gateway-api-integ…

50be7c6

…ration

github-actions bot added size/M Medium PR: 300-599 lines changed and removed size/M Medium PR: 300-599 lines changed labels Nov 28, 2025

Add proposal for operator registry integration via Gateway API #2591

Are you sure you want to change the base?

Add proposal for operator registry integration via Gateway API #2591

Uh oh!

Conversation

JAORMX commented Nov 14, 2025

Summary

Key Features

Two Discovery Methods

Annotations

Design Decisions

Implementation Phases

Uh oh!

codecov bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

rdimitrov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmartinol left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JAORMX commented Nov 24, 2025

Uh oh!

dmartinol commented Nov 26, 2025

Uh oh!

dmartinol commented Nov 26, 2025

Uh oh!

JAORMX commented Nov 26, 2025

Uh oh!

JAORMX commented Nov 26, 2025

Uh oh!

dmartinol commented Nov 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

codecov bot commented Nov 17, 2025 •

edited

Loading