Feat: mcp-gateway support for tags as a grouping mechanism for tools, potentially plugins, etc.

[terylt]

Is your feature request related to a problem? Please describe.

Currently the MCP gateway supports Virtual Services as a mechanism for grouping tools. A simple yet powerful addition would be to adding tags as a mechanism for grouping and searching for tools. Tags would allow you to group on multiple dimensions

Summary

Add support for flexible, multi-dimensional tagging on MCPServer resources and individual tools to enable advanced search, policy application, cost tracking, compliance management, and lifecycle automation.

Motivation

Current State:

• VirtualMCPServers provide single-dimension grouping (e.g., by function or team)
• No built-in way to classify tools across orthogonal dimensions
• Policy application is limited to resource-level targeting
• Tool discovery is static and predefined

Desired State:

• Tag servers and tools across multiple dimensions: environment, department, compliance, criticality, cost, sensitivity, region, stability, etc.
• Enable dynamic tool discovery via tag queries: "find all production-ready, HIPAA-compliant finance tools"
• Apply policies based on tag combinations: rate limit premium tools, require MFA for restricted data
• Track usage and costs by business dimensions (department, cost center, etc.)
• Manage tool lifecycle (deprecation, sunset) via tags
• Apply guardrails and security plugins based on tags.

Proposed Solution

1. Add Tags to MCPServer CRD

apiVersion: mcp.kagenti.com/v1alpha1
kind: MCPServer
metadata:
  name: finance-tools
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: finance-route
  toolPrefix: "finance_"
  
  # Server-level tags (inherited by all tools)
  tags:
    env: production
    department: finance
    compliance.standard: sox
    cost-tier: premium
    criticality: high
    owner.team: finops
    sensitivity: confidential
    region: us-east
  
  # Optional: Per-tool tag overrides
  toolTags:
    - toolName: "finance_generate_report"
      tags:
        complexity: high
        audit-required: "true"

2. Extend VirtualMCPServer with Tag Queries

apiVersion: mcp.kagenti.com/v1alpha1
kind: VirtualMCPServer
metadata:
  name: production-critical-tools
spec:
  selector:
    tagQuery:
      matchAll:  # AND condition
        - key: env
          operator: In
          values: [production]
        - key: criticality
          operator: In
          values: [critical, high]
      matchNone:  # NOT condition
        - key: stability
          operator: In
          values: [experimental, deprecated]

3. Enable Tag-Based Policy Targeting

apiVersion: kuadrant.io/v1
kind: RateLimitPolicy
metadata:
  name: premium-tier-limits
spec:
  targetRef:
    group: mcp.kagenti.com
    kind: MCPServer
    tagSelector:
      matchLabels:
        cost-tier: premium
        env: production
  limits:
    "premium-tools":
      rates:
        - limit: 1000
          duration: 60
          unit: second

4. API Extensions

# List tools by tags
GET /v1/tools?tags=env:production,department:finance

# Complex queries
GET /v1/tools?tagQuery={"matchAll":[{"key":"env","values":["production"]}]}

# Get all tags for a server
GET /v1/servers/finance-tools/tags

Use Cases

1. Multi-Environment Management: Deploy same tools across dev/staging/prod with different policies
2. Cost Allocation: Track usage by department, cost center, or team
3. Compliance: Identify HIPAA/SOX/PCI-DSS tools and enforce audit requirements
4. Beta Rollouts: Gradually expose experimental features to specific user groups
5. Geographic Compliance: Route users to region-specific tool instances for data residency
6. Lifecycle Management: Automatically deprecate and sunset tools based on dates
7. Agent-Specific Filtering: Show different tool subsets based on agent capabilities

Benefits

• Flexibility: Classify across multiple independent dimensions without hierarchies
• Discovery: Rich queries for dynamic tool selection
• Governance: Apply security, rate limits, and audit policies by attributes
• Observability: Track metrics by business dimensions (department, cost, criticality)
• Cost Management: Allocate and charge back by organizational units
• Compliance: Easily identify regulated tools and enforce controls
• Lifecycle: Manage tool maturity (experimental → beta → stable → deprecated)

Implementation Considerations

Tag Schema

• Format: key:value or namespace.key:value
• Max key length: 63 characters
• Max value length: 253 characters
• Max tags per resource: 50
• Allowed characters: alphanumeric, hyphens, underscores, dots, colons

Tag Inheritance

1. Tool-specific tags override server-level tags
2. VirtualMCPServer tags are additive
3. Tag conflicts result in multi-value arrays

Performance

• Index tags in controller for fast lookups
• Cache tag queries in broker
• Support pagination for large result sets

cc: @shaneutt

[david-martin]

Thanks for taking the time @terylt to flesh out the feature in detail.
I'll share this wider and make some time to read the detail.

In case you haven't seen it, there is a related issue around discovery as well #433

[david-martin]

There's a lot in this feature request.
Here's my simplified view of what I think is being proposed:

• allow adding arbitrary tags to tools, via the MCPServerRegistration CRD spec (formerly MCPServer). These tags would propagate/be made available in various places (e.g. logs, headers, metrics)
• allow selecting tools based on these tags for populating a virtual MCP server via the MCPVirutalServer CRD spec
• provide a set of new APIs for listing tools based these tags (overlaps most with Tool optimization as Gateway feature #433)

Regarding the RateLimitPolicy example, I don't think a change is needed to that CRD to allow limiting based on tags, provided the tags are made available as attributes e.g. headers. (see docs for info on predicates https://docs.kuadrant.io/1.3.x/kuadrant-operator/doc/overviews/rate-limiting/)

@terylt would that be a fair summation?

[terylt]

Hi @david-martin , yes that would be a fair summation. Tagging is a really great way to be able to group entities along different dimensions, and in doing so, can allow you to apply things like guardrails and such in simpler ways.

[david-martin]

Discussed on backlog refinement 3/3/26:

• let's do a poc here to add some new tools to help educate the agent on what tools are available at the gateway
• thinking 2 new tools. 1 for listing all tags, and 1 for giving a filtered list of tools (in MCP spec format) given an array of tags.
  • the reason for using tools here is to avoid a new endpoint(s) and going outside of the MCP spec to deliver this feature
• the MCPServerRegistration CRD can have a list of tags, similar to the recommendation in the description of this issue