Tags — MCP Tools

Endpoint tags: create, assign, reorder and bulk update. This page documents the Tags group of the Routebase MCP server, with the scope and the parameters of each tool.

A session that stages its tools advertises this group once the agent calls enable_toolset with the slug tags. Full-access keys, scoped keys and OAuth sessions see every tool they are allowed to call without that step.

bulk_update_tags

Add and/or remove tags across many endpoints at once, leaving their other tags alone. Give tagsToAdd, tagsToRemove or both. Use this to add or remove tags across many endpoints; to replace one endpoint's whole tag set use set_endpoint_tags. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
endpointIds	string	Yes	Endpoint IDs (GUIDs) to change, comma-separated
tagsToAdd	string	No	Tag names to add, comma-separated (optional)
tagsToRemove	string	No	Tag names to remove, comma-separated (optional)

create_tag

Create an endpoint tag in a spec version. Tags group endpoints in the designer and become root-level OpenAPI tags on export; the description is rendered on the tag's documentation portal pages. Use this for a single new tag; to derive tags from the paths of an imported spec use generate_tags_from_paths. The 3.2 fields summary, parent and kind need a 3.2 spec. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version to add the tag to
name	string	Yes	Tag name (e.g. 'Users', 'Billing') — this is what endpoints reference
description	string	No	Optional Markdown description (CommonMark; ```mermaid fences supported)
icon	string	No	Optional icon (emoji or icon name)
summary	string	No	OpenAPI 3.2 summary (short label)
parent	string	No	OpenAPI 3.2 parent: name of a tag in the same version
kind	string	No	OpenAPI 3.2 kind, e.g. 'nav', 'badge', 'audience'

delete_tag

Delete an endpoint tag from a spec version. Endpoints carrying the tag lose it; the endpoints themselves are untouched. Use this to remove the tag itself; to take it off individual endpoints only use bulk_update_tags. Requires project context.

Required scope: specs:delete

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version the tag belongs to
tagId	string	Yes	Public ID (GUID) of the tag to delete

generate_tags_from_paths

Derive tags from the endpoint paths of a version and assign them — '/users/{id}' becomes 'users'. Useful right after importing a spec that has no tags. Existing tags are kept. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version to generate tags for

get_tag

Get a single endpoint tag with its description, icon, display order and endpoint count. Use this when you already have the tag id; to browse a spec's tags or find an id use list_tags. Requires project context.

Required scope: specs:read

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
tagId	string	Yes	Public ID (GUID) of the tag
versionId	string	No	Optional version ID (GUID) the tag belongs to

list_tags

List the endpoint tags of an API specification, including their Markdown descriptions and display order. Tag descriptions are exported as root-level OpenAPI tags and shown in the documentation portal. Use this to browse tags or find a tag id; for one tag by id use get_tag. Requires project context (call set_context first).

Required scope: specs:read

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	No	Optional version ID (GUID) to filter tags by a specific version

reorder_tags

Set the display order of a version's endpoint tags. Pass every tag ID in the order you want — the order drives the designer tree and the documentation portal navigation. Use this to change display order only; to rename a tag or edit its description use update_tag_description. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version
tagIds	string	Yes	Tag IDs (GUIDs) in the desired display order, comma-separated

set_endpoint_tags

Replace the tag list of one or more endpoints. Each item names an endpoint and the exact set of tag names it should carry afterwards — tags not listed are removed from that endpoint. Use bulk_update_tags to add or remove without replacing. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version
assignmentsJson	string	Yes	JSON array of assignments: [{"endpointId":"","tags":["Users","Admin"]}]. An empty tags array clears that endpoint's tags.

update_tag_description

Update an endpoint tag: its Markdown description, name, icon and the OpenAPI 3.2 fields summary, parent and kind (3.2 specs; an empty string clears). Omit a field to keep the current value. The description becomes the root-level OpenAPI tag description on export/publish and is rendered on the tag's documentation portal pages (CommonMark, ```mermaid fences supported). Renaming a tag also updates the endpoints that carry it. Get the tag's id and rowVersion from list_tags. Requires project context.

Required scope: specs:write

Parameter	Type	Required	Description
specId	string	Yes	Public ID (GUID) of the API specification
versionId	string	Yes	Public ID (GUID) of the spec version the tag belongs to
tagId	string	Yes	Public ID (GUID) of the tag to update
rowVersion	string	Yes	Base64-encoded row version of the tag (for concurrency control)
description	string	No	New Markdown description (CommonMark; ```mermaid fences supported), or omit to keep the current description
name	string	No	New tag name, or omit to keep the current name
icon	string	No	New icon (emoji or icon name), or omit to keep the current icon
summary	string	No	OpenAPI 3.2 summary; '' clears
parent	string	No	OpenAPI 3.2 parent tag name; '' clears
kind	string	No	OpenAPI 3.2 kind ('nav', 'badge', 'audience'); '' clears