Skip to Content
MCP Platform DocumentationHosting MCP serversTag-based tool filtering

A single MCP server can expose dozens or hundreds of tools. Tag-based tool filtering lets a client connect to a focused subset of those tools by selecting one or more tags, without standing up a separate server or toolset for every use case.

Tags come from the tools themselves: OpenAPI operation tags, Gram Functions tag definitions, and tag overrides applied through tool variations. Once tag-based filtering is enabled on a server, the install page surfaces the available tags and a ready-to-use install URL for each one.

Why use tag-based filtering

A large toolset gives an MCP server broad coverage, but a client rarely needs every tool at once. Connecting with too many tools can degrade an LLM’s tool selection and add noise to each request.

Tag-based filtering keeps a single server as the source of truth while letting each consumer scope down to the tools relevant to a task, such as billing, flags, or support. Tag a tool once, and it appears under that tag for every consumer of the server.

Enable tag-based filtering

Tag-based filtering is surfaced on a server once a tool variations group is assigned to the MCP server on its Settings tab. The tool variations group is what tells Gram which tags are available, populates the install page, and generates the per-tag install URLs.

To enable tag-based filtering:

  • Tag the tools that should be filterable. Tags come from OpenAPI operation tags, Gram Functions tags, or tool variations.
  • Assign a tool variations group to the MCP server on its Settings tab.
  • Open the server’s install page to confirm the available tags and per-tag install URLs appear.

Note

Available tags and per-tag install URLs are not surfaced on the install page until filtering is explicitly enabled for the MCP server.

The tags URL parameter

Filter a server’s tools by appending the tags query parameter to the MCP server URL. The parameter is comma-separated and accepts one or more tags:

https://app.getgram.ai/mcp/default/should-i-push/default?tags=billing,flags

Multiple tags are a union: a tool is included if it matches any of the requested tags, not all of them. Requesting ?tags=billing,flags returns every tool tagged billing or flags.

The install page provides a pre-filled URL for each available tag, so consumers can copy a tag-scoped URL directly rather than constructing the parameter by hand.

Default behavior

Tag-based filtering is opt-in per request:

  • No tags parameter returns the full, unfiltered tool list. A server with no tags parameter behaves exactly as it does today.
  • A tag filter excludes every tool without a matching tag. This includes untagged tools. Once a request filters by tag, only tools carrying a matching tag are returned.

Effective-tag precedence rules

A tool’s effective tags determine which filters it appears under. Source tags (from OpenAPI or Gram Functions) and tool variation tags combine according to the following precedence:

  • A tool variation that sets tags replaces the source tags. The variation tags become the tool’s complete tag set; the source tags no longer apply.
  • An explicit empty tag set removes the tool from every filter. A variation that sets tags to an empty set excludes the tool from all tag filters, while still leaving it available on the unfiltered server.
  • An unset variation leaves the source tags authoritative. When a variation does not touch tags, the tool keeps the tags from its OpenAPI operation or Gram Functions definition.
  • Untagged tools are excluded under any filter. A tool with no effective tags appears only on the unfiltered server and never under a tags filter.

See tool variations for how to set, override, or clear a tool’s tags from the dashboard.

The install page

Once tag-based filtering is enabled, the server’s install page lists the available tags alongside the standard installation instructions. Each tag includes a copyable install URL with the tags parameter pre-filled, so consumers can connect to a tag-scoped view of the server in a single step.

Find the install page link under the MCP Installation section of the MCP server’s details page. See Deploy an MCP server for where to locate and share it.

Next steps

Last updated on