|
| 1 | +--- |
| 2 | +title: "Tag-based tool filtering" |
| 3 | +description: "Let MCP clients connect to a focused subset of an MCP server's tools by tagging tools and filtering on install with the tags URL parameter." |
| 4 | +sidebar: |
| 5 | + order: 2 |
| 6 | +--- |
| 7 | + |
| 8 | +import { Callout } from "@/mdx/components"; |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +## Why use tag-based filtering |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +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. |
| 19 | + |
| 20 | +## Enable tag-based filtering |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +To enable tag-based filtering: |
| 25 | + |
| 26 | +- Tag the tools that should be filterable. Tags come from [OpenAPI operation tags](/docs/mcp/getting-started/openapi#tag-tools-for-filtering), [Gram Functions tags](/docs/mcp/build/gram-functions/tool-tags), or [tool variations](/docs/mcp/reference/concepts/tool-variations#tags). |
| 27 | +- Assign a tool variations group to the MCP server on its **Settings** tab. |
| 28 | +- Open the server's install page to confirm the available tags and per-tag install URLs appear. |
| 29 | + |
| 30 | +<Callout title="Note" type="info"> |
| 31 | + Available tags and per-tag install URLs are not surfaced on the install page |
| 32 | + until filtering is explicitly enabled for the MCP server. |
| 33 | +</Callout> |
| 34 | + |
| 35 | +## The tags URL parameter |
| 36 | + |
| 37 | +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: |
| 38 | + |
| 39 | +```bash |
| 40 | +https://app.getgram.ai/mcp/default/should-i-push/default?tags=billing,flags |
| 41 | +``` |
| 42 | + |
| 43 | +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`. |
| 44 | + |
| 45 | +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. |
| 46 | + |
| 47 | +## Default behavior |
| 48 | + |
| 49 | +Tag-based filtering is opt-in per request: |
| 50 | + |
| 51 | +- **No `tags` parameter returns the full, unfiltered tool list.** A server with no `tags` parameter behaves exactly as it does today. |
| 52 | +- **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. |
| 53 | + |
| 54 | +## Effective-tag precedence rules |
| 55 | + |
| 56 | +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: |
| 57 | + |
| 58 | +- **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. |
| 59 | +- **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. |
| 60 | +- **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. |
| 61 | +- **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. |
| 62 | + |
| 63 | +See [tool variations](/docs/mcp/reference/concepts/tool-variations#tags) for how to set, override, or clear a tool's tags from the dashboard. |
| 64 | + |
| 65 | +## The install page |
| 66 | + |
| 67 | +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. |
| 68 | + |
| 69 | +Find the install page link under the **MCP Installation** section of the MCP server's details page. See [Deploy an MCP server](/docs/mcp/build/hosting/deploy-mcp-server) for where to locate and share it. |
| 70 | + |
| 71 | +## Next steps |
| 72 | + |
| 73 | +- [Tag Gram Functions tools](/docs/mcp/build/gram-functions/tool-tags) with the top-level `tags` property. |
| 74 | +- [Tag OpenAPI-sourced tools](/docs/mcp/getting-started/openapi#tag-tools-for-filtering) with native operation tags. |
| 75 | +- [Override tags with tool variations](/docs/mcp/reference/concepts/tool-variations#tags) from the dashboard. |
| 76 | +- [Deploy an MCP server](/docs/mcp/build/hosting/deploy-mcp-server) and share its install page. |
0 commit comments