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, Functions tags, or tag overrides set 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:

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. 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 for where to locate and share it.

Next steps

• Tag Functions tools with the top-level tags property.
• Tag OpenAPI-sourced tools with native operation tags.
• Override tags from the dashboard with tool variations.
• Share the server’s install page; see Distribution.