Skip to content
This repository was archived by the owner on Oct 19, 2026. It is now read-only.

Commit 045bcda

Browse files
authored
Merge branch 'main' into framework/nestjs
2 parents 0c76a40 + a2303ef commit 045bcda

30 files changed

Lines changed: 850 additions & 791 deletions

‎_meta.global.tsx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -682,9 +682,6 @@ const meta = {
682682
"cloudflare-deployment": {
683683
title: "Deploy to Cloudflare Workers",
684684
},
685-
"gram-deployment": {
686-
title: "Deploy to Gram",
687-
},
688685
"custom-prompts": {
689686
title: "Custom Prompts",
690687
},
@@ -749,6 +746,9 @@ const meta = {
749746
"tool-annotations": {
750747
title: "Tool annotations",
751748
},
749+
"tool-tags": {
750+
title: "Tool tags",
751+
},
752752
"mcp-sdk": {
753753
title: "Using the MCP SDK",
754754
},
@@ -795,6 +795,9 @@ const meta = {
795795
"deploy-mcp-server": {
796796
title: "Deploy an MCP server",
797797
},
798+
"tool-filtering": {
799+
title: "Tag-based tool filtering",
800+
},
798801
"tool-call-healing": {
799802
title: "Tool call healing",
800803
},
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: "Tool tags"
3+
description: "Tag Gram Functions tools so MCP clients can connect to a focused subset of an MCP server using tag-based tool filtering."
4+
---
5+
6+
## What are tool tags?
7+
8+
Tags are short labels that group related tools, such as `billing`, `flags`, or `support`. When tag-based tool filtering is enabled on an MCP server, a client can connect to a focused subset of the server's tools by selecting one or more tags. See [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering) for what tags enable and how the `tags` URL parameter works.
9+
10+
The Gram Functions Framework supports tags directly in tool definitions. Add tags to any tool using the top-level `tags` property:
11+
12+
```typescript
13+
import { Gram } from "@gram-ai/functions";
14+
import * as z from "zod/mini";
15+
16+
const gram = new Gram().tool({
17+
name: "create_invoice",
18+
description: "Create an invoice for a customer",
19+
tags: ["billing", "finance"],
20+
inputSchema: { customerId: z.string(), amount: z.number() },
21+
async execute(ctx, input) {
22+
const invoice = await createInvoice(input.customerId, input.amount);
23+
return ctx.json(invoice);
24+
},
25+
});
26+
27+
export default gram;
28+
```
29+
30+
Tags persist across deployments, so a tool keeps its tags when the function is rebuilt and pushed again.
31+
32+
## Tags and tag-based filtering
33+
34+
Tags defined on a Gram Function become the tool's source tags. They are available as filters once tag-based filtering is enabled on the MCP server, and they can be overridden from the dashboard.
35+
36+
A [tool variation](/docs/mcp/reference/concepts/tool-variations#tags) that sets tags replaces the tags defined here. See [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering#effective-tag-precedence-rules) for the full precedence rules that decide which tags a tool is filtered by.
37+
38+
## Next steps
39+
40+
- Enable [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering) on an MCP server.
41+
- Override tags from the dashboard with [tool variations](/docs/mcp/reference/concepts/tool-variations#tags).
42+
- Learn more about the [Functions Framework](/docs/mcp/build/gram-functions/functions-framework).

‎docs/mcp/build/hosting/deploy-mcp-server.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ Under the **MCP Installation** section, you can edit and copy the MCP installati
6464
Your MCP server is now live. Here are some next steps to consider:
6565

6666
- **Iterate on tool descriptions:** Refine tool definitions and use [tool variations](/docs/mcp/reference/concepts/tool-variations) to help LLMs better understand and invoke them accurately.
67+
- **Filter tools by tag:** Enable [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering) so clients can connect to a focused subset of the server's tools.
6768
- **Create custom toolsets:** Group tools by task to design structured, step-by-step workflows tailored to specific use cases.
6869
- **Integrate with frameworks:** Use the Gram Python or TypeScript SDK to build agentic workflows. On the **Playground** page, you can select a ready-to-use code snippet in [Python](https://pypi.org/project/gram-ai/) or [JavaScript](https://www.npmjs.com/package/@gram-ai/sdk).
6970

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
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.

‎docs/mcp/build/integrate/clients/using-mistral-with-gram-mcp-servers.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ Scroll down to the **Raw Configuration** section and copy the raw configuration.
100100

101101
## Connecting Mistral to your Gram-hosted MCP server
102102

103-
Mistral supports a **Custom Connector** that you can configure to connect to your Gram-hosted MCP server. See Mistral's guide for more details: [Configuring a custom connector](https://help.mistral.ai/en/articles/393572-configuring-a-custom-connector).
103+
Mistral supports a **Custom Connector** that you can configure to connect to your Gram-hosted MCP server. See Mistral's guide for more details: [Configuring a custom connector](https://docs.mistral.ai/le-chat/knowledge-integrations/connectors/mcp-connectors).
104104

105105
### Add a Custom Connector in Mistral
106106

‎docs/mcp/build/integrate/integrate-mcp.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Specifically we provide detailed instructions on:
1313
- Connecting with CLI tools such as [Using Claude Code with Gram-hosted MCP servers](/docs/mcp/build/integrate/clients/using-claude-code-with-gram-mcp-servers).
1414
- Using MCP programmatically through APIs such as [Using OpenAI API with Gram-hosted MCP servers](/docs/mcp/build/integrate/api-clients/using-openai-api-with-gram-mcp-servers).
1515
- [Exporting server configuration](/docs/mcp/build/integrate/export-server-configuration) as JSON for documentation and integration.
16+
- Connecting to a focused subset of a server's tools with [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering).
1617
- Building example applications like [Add AI chat to an existing app](/docs/mcp/build/examples/adding-ai-chat-to-your-app).
1718

1819
<!-- See the full list in the sidebar. Is there something you want added? Feel free to [open an issue](https://github.com/speakeasy-api/gram-docs/issues)! -->

‎docs/mcp/getting-started/openapi.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,10 +216,26 @@ workflows by selecting a language and integration type.
216216

217217
![Gram agents integration](/assets/docs/gram/img/blog/the-easiest-way-to-host-mcp-servers/gram-agentic-workflow.png)
218218

219+
## Tag tools for filtering
220+
221+
Native OpenAPI operation `tags` are ingested automatically and become filter tags on the generated tools:
222+
223+
```yaml filename="openapi.yaml" {4}
224+
paths:
225+
/invoices:
226+
post:
227+
tags: [billing, finance]
228+
summary: Create an invoice
229+
operationId: createInvoice
230+
```
231+
232+
With [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering) enabled, MCP clients can connect to a focused subset of the server's tools by selecting one or more tags. Tags can also be overridden later with [tool variations](/docs/mcp/reference/concepts/tool-variations#tags).
233+
219234
## What's next?
220235
221236
The following resources will help you get the most out of your Gram MCP server:
222237
223238
- [Learn about best practices for curating toolsets.](/docs/mcp/build/toolsets/advanced-tool-curation)
224239
- [Improve tool names and descriptions](/docs/mcp/reference/concepts/tool-variations)
240+
- [Filter tools by tag with tag-based tool filtering.](/docs/mcp/build/hosting/tool-filtering)
225241
- [Add tools using the Gram TypeScript Framework.](/docs/mcp/getting-started/typescript)

‎docs/mcp/getting-started/typescript.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,4 +152,5 @@ The following resources will help you get the most out of your Gram MCP server:
152152

153153
- [Learn more about the Gram Functions framework.](/docs/mcp/build/gram-functions)
154154
- [Learn about best practices for curating toolsets.](/docs/mcp/build/toolsets/advanced-tool-curation)
155+
- [Tag tools so clients can filter by tag.](/docs/mcp/build/gram-functions/tool-tags)
155156
- [Add OpenAPI-sourced tools to your MCP server.](/docs/mcp/getting-started/openapi)

‎docs/mcp/reference/concepts/tool-sources.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,12 @@ The `x-gram` extension also supports [response filtering](/docs/mcp/build/toolse
291291

292292
Using the `x-gram` extension is optional. With Gram's [tool variations](/docs/mcp/reference/concepts/tool-variations) feature, you can modify a tool's name and description when curating tools into toolsets. However, it might be worth using the `x-gram` extension to make your OpenAPI document clean, descriptive, and LLM-ready before bringing it into Gram, so your team doesn't need to fix tool names and descriptions later.
293293

294+
### Operation tags
295+
296+
Native OpenAPI operation `tags` are ingested automatically and become the source tags for the generated tool. In the example above, the `get_product` tool inherits the `ecommerce` tag from its operation.
297+
298+
These tags drive [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering), which lets MCP clients connect to a focused subset of a server's tools. A tag set through [tool variations](/docs/mcp/reference/concepts/tool-variations#tags) overrides the operation tags; see the [precedence rules](/docs/mcp/build/hosting/tool-filtering#effective-tag-precedence-rules) for details.
299+
294300
### Limitations of OpenAPI 3.0.x
295301

296302
Many LLMs don't support the JSON Schema version used in OpenAPI 3.0.x documents. When these documents are uploaded to Gram, they are transparently upgraded to 3.1.0 using the steps defined in [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0). When this happens you might notice that line numbers no longer match the original OpenAPI document. It's recommended to upgrade your OpenAPI documents to 3.1.x to have a more streamlined experience.

‎docs/mcp/reference/concepts/tool-variations.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,11 @@ Similarly, to edit a tool's description, click the 3 dots and select **Edit desc
3333
type="video/mp4"
3434
/>
3535
</video>
36+
37+
## Tags
38+
39+
The **Tools** tab also lets you add or override a tool's tags, just like editing its name or description. Tags assigned here participate in [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering), which lets MCP clients connect to a focused subset of a server's tools.
40+
41+
To edit a tool's tags, click the 3 dots and update the tags in the modal that opens.
42+
43+
Tag variations take precedence over a tool's source tags (from OpenAPI operations or Gram Functions). Setting tags through a variation replaces the source tags, and clearing them to an empty set removes the tool from every tag filter. For the full precedence rules, see [tag-based tool filtering](/docs/mcp/build/hosting/tool-filtering#effective-tag-precedence-rules).

0 commit comments

Comments
 (0)