# 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 for every use case. Tags come from the tools themselves: OpenAPI operation tags, Speakeasy Functions tag definitions, and tag overrides set from the dashboard. 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 tool selection 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 in the **Tool Filtering** section of its **Settings** tab, reached from **MCP Gateway > MCP** in the project sidebar. The section is described as filtering the tools exposed by the server based on their tags, with all tools returned by default unless filtering is enabled and a `tags` query parameter is provided. The tool variations group is what tells the platform 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/mcp-gateway/building-servers/openapi#tag-tools-for-filtering), [Functions tags](/docs/ai-control-plane/mcp-gateway/building-servers/functions/tool-tags), or [tag overrides set from the dashboard](#override-tags-from-the-dashboard). - Assign a tool variations group to the MCP server in the **Tool Filtering** section of 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: ```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. ## Override tags from the dashboard A tool's tags can be added or overridden from the dashboard, as a [tool variation](/docs/ai-control-plane/mcp-gateway#editing-a-tool). Open the tool's three-dot actions menu on the **Tools** tab of a built server or of a source's detail page, select **Edit tags**, and update the tags in the dialog that opens. **Edit tags** is available for tools generated from OpenAPI documents and functions. Tags set this way take precedence over the tags from the tool's source, as the rules below describe. ## Effective-tag precedence rules A tool's effective tags determine which filters it appears under. Source tags (from OpenAPI or 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 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. ## 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 [Distribution](/docs/ai-control-plane/mcp-gateway#distribution) for where to locate and share it. ## Next steps - [Tag Functions tools](/docs/ai-control-plane/mcp-gateway/building-servers/functions/tool-tags) with the top-level `tags` property. - [Tag OpenAPI-sourced tools](/docs/ai-control-plane/mcp-gateway/building-servers/openapi#tag-tools-for-filtering) with native operation tags. - [Override tags from the dashboard](#override-tags-from-the-dashboard) with tool variations. - Share the server's install page; see [Distribution](/docs/ai-control-plane/mcp-gateway#distribution).