# Tag-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](/docs/ai-control-plane/connect/sources/openapi#tag-tools-for-filtering), [Gram Functions tags](/docs/ai-control-plane/connect/sources/gram-functions/tool-tags), or [tool variations](/docs/ai-control-plane/reference/concepts/tool-variations#tags). - 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. 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: ```bash 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](/docs/ai-control-plane/reference/concepts/tool-variations#tags) 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](/docs/ai-control-plane/distribute/mcp-servers) for where to locate and share it. ## Next steps - [Tag Gram Functions tools](/docs/ai-control-plane/connect/sources/gram-functions/tool-tags) with the top-level `tags` property. - [Tag OpenAPI-sourced tools](/docs/ai-control-plane/connect/sources/openapi#tag-tools-for-filtering) with native operation tags. - [Override tags with tool variations](/docs/ai-control-plane/reference/concepts/tool-variations#tags) from the dashboard. - [Deploy an MCP server](/docs/ai-control-plane/distribute/mcp-servers) and share its install page.