docs: Add tool discovery proposal by rubambiza · Pull Request #227 · kubernetes-sigs/kube-agentic-networking

rubambiza · 2026-04-06T20:48:48Z

Summary

Proposes optional, opt-in tool discovery for KAN: a controller that calls tools/list on MCP backends, validates schemas, and surfaces discovered tools in XBackend.status
Enables policy validation against real backend state, operator visibility via kubectl, and a foundation for response filtering
Discovery is advisory (does not affect policy enforcement) and opt-in via annotation

Phasing

Phase 1: In-cluster discovery over plain HTTP with graceful failure for auth-required backends
Phase 2: External backends with TLS/authentication (deferred pending Backend spec stabilization)
Phase 3: AccessPolicy cross-referencing against discovered tools

Prior discussion

This proposal was initially drafted and reviewed on the fork PR (rubambiza#1) with feedback from @evaline-ju and @david-martin incorporated.

Test plan

Community review of proposal content and API design
Alignment on community consensus points (XBackend.status location, MCP client library, sync interval)

Signed-off-by: Gloire Rubambiza <gloire@ibm.com>

netlify · 2026-04-06T20:48:54Z

✅ Deploy Preview for kube-agentic-networking ready!

Name	Link
🔨 Latest commit	`6a59a19`
🔍 Latest deploy log	https://app.netlify.com/projects/kube-agentic-networking/deploys/69e99a98f65e37000802c668
😎 Deploy Preview	https://deploy-preview-227--kube-agentic-networking.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

k8s-ci-robot · 2026-04-06T20:48:55Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: rubambiza
Once this PR has been reviewed and has the lgtm label, please assign david-martin for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2026-04-06T20:48:58Z

Hi @rubambiza. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

evaline-ju · 2026-04-07T15:51:33Z

/ok-to-test

Signed-off-by: Gloire Rubambiza <gloire@ibm.com>

LiorLieberman · 2026-04-30T15:00:24Z

/cc

david-martin

Given the XBackend resource won't be in v1alpha1, we should hold this for now.
I see the value in having a controller being able to list and report back tools from mcp servers for more than AccessPolicy tool validation. For example, it can help with configuration validation, or surfacing of tools for informational purposes beyond auth.

I tend to like the standalone (extension?) approach, as making it a required piece could be a barrier to some agentic networking implementations, and could potentially be unwanted in some installations for various reasons (unwanted load, difficult to configure auth for some mcp servers)

/hold

david-martin · 2026-05-07T11:02:20Z

+
+## Non-Goals
+
+- **`tools/list` response filtering.** Filtering the `tools/list` response


Good to call this out.
I wonder, should we be more explicit to avoid confusion here as there are 2 identities at play here.
The identity to use when this new controller calls tools/list for populating the backend status,
and the identity when an agent/user is calling tool list?
The latter tool/list filtering I see as dynamic at list time, performing an authZ function, and driven by the rules in AccessPolicy

david-martin · 2026-05-07T11:46:23Z

+**Phase 1: In-cluster discovery (plain HTTP).** XBackend status extension,
+discovery controller, schema validation, `list_changed` support, drift
+detection. The controller connects to backends using the service name and port
+from `XBackend.spec.mcp` over plain HTTP. This is sufficient for in-cluster


david-martin · 2026-05-07T11:47:49Z

+5. **Updates** `XBackend.status.discoveredTools[]` with validated tools only.
+6. **Listens** for `tools/list_changed` notifications on backends that declare
+   the `listChanged` capability, triggering immediate re-discovery.
+7. **Falls back to polling** (configurable interval, default 30s) for backends


30s probably too aggresive.
5 minutes maybe?

david-martin · 2026-05-07T11:58:52Z

+An `XAccessPolicy` referencing a non-existent tool receives a Warning:
+
+```yaml
+apiVersion: agentic.prototype.x-k8s.io/v0alpha0


agentic.networking.x-k8s.io

david-martin · 2026-05-07T12:03:01Z

+### AccessPolicy Validation
+
+The existing AccessPolicy reconciler is extended to cross-reference
+`rules[].authorization.tools[]` against `XBackend.status.discoveredTools`:


note the change to method based matching in v1alpha1

kube-agentic-networking/api/v1alpha1/accesspolicy_types.go

Line 197 in d2507a7

// +kubebuilder:validation:XValidation:rule="has(self.params) && self.params.size() > 0 ? self.name in ['prompts/get', 'tools/call', 'resources/subscribe', 'resources/unsubscribe', 'resources/read'] : true",message="Params can only be specified for get, call, subscribe, unsubscribe, or read methods"

Will need to consider that and update here.

docs: Add tool discovery proposal

33e8775

Signed-off-by: Gloire Rubambiza <gloire@ibm.com>

k8s-ci-robot requested a review from david-martin April 6, 2026 20:48

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Apr 6, 2026

k8s-ci-robot requested a review from LiorLieberman April 6, 2026 20:48

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Apr 6, 2026

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Apr 6, 2026

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Apr 7, 2026

LiorLieberman mentioned this pull request Apr 7, 2026

REQUEST: New membership for @rubambiza kubernetes/org#6134

Closed

11 tasks

docs: Scope tool discovery proposal to MCP, note A2A as out of scope

6a59a19

Signed-off-by: Gloire Rubambiza <gloire@ibm.com>

david-martin reviewed May 7, 2026

View reviewed changes

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label May 7, 2026

david-martin reviewed May 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add tool discovery proposal#227

docs: Add tool discovery proposal#227
rubambiza wants to merge 2 commits into
kubernetes-sigs:mainfrom
rubambiza:proposal-tool-discovery-upstream

rubambiza commented Apr 6, 2026

Uh oh!

netlify Bot commented Apr 6, 2026 •

edited

Loading

Uh oh!

k8s-ci-robot commented Apr 6, 2026

Uh oh!

k8s-ci-robot commented Apr 6, 2026

Uh oh!

evaline-ju commented Apr 7, 2026

Uh oh!

LiorLieberman commented Apr 30, 2026

Uh oh!

david-martin left a comment

Uh oh!

david-martin May 7, 2026

Uh oh!

david-martin May 7, 2026

Uh oh!

david-martin May 7, 2026

Uh oh!

david-martin May 7, 2026

Uh oh!

david-martin May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		## Non-Goals

		- `tools/list` response filtering. Filtering the `tools/list` response

Conversation

rubambiza commented Apr 6, 2026

Summary

Phasing

Prior discussion

Test plan

Uh oh!

netlify Bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kube-agentic-networking ready!

Uh oh!

k8s-ci-robot commented Apr 6, 2026

Uh oh!

k8s-ci-robot commented Apr 6, 2026

Uh oh!

evaline-ju commented Apr 7, 2026

Uh oh!

LiorLieberman commented Apr 30, 2026

Uh oh!

david-martin left a comment

Choose a reason for hiding this comment

Uh oh!

david-martin May 7, 2026

Choose a reason for hiding this comment

Uh oh!

david-martin May 7, 2026

Choose a reason for hiding this comment

Uh oh!

david-martin May 7, 2026

Choose a reason for hiding this comment

Uh oh!

david-martin May 7, 2026

Choose a reason for hiding this comment

Uh oh!

david-martin May 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify Bot commented Apr 6, 2026 •

edited

Loading