Skip to Content
Access Policies

Policy Tags

Tag agents, MCP servers and tools so one policy rule covers all of them, including ones you add later

Once you have more than a few agents and MCP servers, naming each one in a policy rule stops scaling, and the ones you add later aren't covered. Policy tags group agents, MCP servers and tools, so one rule can match a policy tag and cover everything that carries it, including what you add later.

Policy Tags page with Agent and Resource tabs and a table of policy tags
The Policy Tags page: one tab for each kind of policy tag

Agent and Resource policy tags

The Policy Tags page has a tab for each kind of policy tag, and each kind goes on different things:

  • Agent – goes on agents, such as trusted or coding. Rules match it in the Agent pill.
  • Resource – goes on MCP servers and their tools, such as prod or pii. Rules match it in the MCP and Tools pills.

The two kinds are kept apart. An Agent tag and a Resource tag with the same name are still different tags. Built-in tags are Resource tags only.

Built-in policy tags

SecureAuth applies built-in tags to catalog tools, and to new tools from their annotations. Built-in tags describe what a tool does, and you can match them in a rule's Tools pill.

Policy tagMeaning
read-onlyReads data without changing anything.
writeCreates or changes data; reversible or additive.
destructiveDeletes, overwrites, or makes an irreversible change.
externalReaches outside the organization: sends messages or email, posts publicly, or fetches arbitrary URLs.

Every catalog tool has exactly one of read-only, write, or destructive, plus external when it reaches outside the organization. A tool carries both the built-in tags SecureAuth applies and the ones you assign.

  • You can't edit or delete built-in tags, or give a Resource tag a built-in tag's name.
  • You can't remove the built-in tags SecureAuth applies to catalog tools.
  • You can assign built-in tags to any tool yourself, and remove the ones you assigned.

Built-in tags appear on the Resource tab, in a Built-in section below your own policy tags.

Policy Tags page on the Resource tab, with your own policy tags above a Built-in section listing read-only, write, destructive and external
Built-in tags sit in their own section on the Resource tab

Policy tags from tool annotations

An MCP server can describe each tool with annotations, short hints about what the tool does that the MCP specification defines. When SecureAuth first discovers a tool that isn't a catalog tool, it reads the tool's annotations and assigns built-in tags. That includes a tool on a custom server and a tool that a provider adds to a catalog server.

AnnotationBuilt-in tag
readOnlyHint: trueread-only
destructiveHint: truedestructive
destructiveHint: falsewrite
openWorldHint: trueexternal

SecureAuth ignores destructiveHint when readOnlyHint is true, as the specification does. A tool without these annotations gets no built-in tags.

SecureAuth assigns these policy tags once, so later changes to the server's annotations don't change them. You can remove or replace them, like policy tags you assign. Agent Trail records each assignment, attributed to System.

Limits

  • Same-name policy tags – a Resource tag you created with a built-in tag's name, such as write, is matched along with the built-in one by a condition like 'write' in mcp.tool.tags. Rename your tag to keep its old meaning.
  • Annotations are unverified – a server can mark a tool readOnlyHint: true even if it changes data, and a rule that allows read-only tools then allows it. Add only resources you trust, and check the policy tags on their new tools.
  • Some tools have no built-in policy tag – a tool that isn't a catalog tool gets none when its server sends no annotations, or when SecureAuth found it before it started reading annotations. A deny rule that matches a policy tag doesn't cover these tools, so assign built-in tags yourself, or allow only read-only tools and rely on the default deny.

Managing policy tags

Open Policy Tags under Policy Controls in the sidebar and pick the Agent or Resource tab. Click New policy tag to create one, or click a row to rename it or change its color. A name can be up to 50 characters and must be unique among policy tags of its kind, ignoring case.

Managing policy tags requires the manage_tags permission. Without it, the Policy Tags page and the tag controls on detail pages are read-only.

New policy tag dialog with a name field and color picker
Creating a policy tag: name and color

Deleting a policy tag

Open the row's menu on the Policy Tags page and choose Delete. Every rule that matches the policy tag stops matching it, and so does any condition that tests it by name:

  • An allow rule stops granting access.
  • A deny rule stops blocking, so its protection is gone.

The delete dialog shows how many things lose the policy tag and lists every policy that matches it. A policy that may only test the policy tag in a condition is marked may reference via condition. The dialog also highlights active deny rules, so check them before you confirm. If it can't load your policies, it says so instead, so check Access Policies yourself before you confirm.

Assigning policy tags

  • MCP servers and tools – open a server from MCP Servers & Tools, then click Add policy tag beside the server's tabs to tag the whole server, or on a tool's row to tag one tool. The tool control also offers the built-in tags. A tool waiting for review shows Review there instead, until you review it.
  • Agents – open an agent from the Agent Catalog tab of Agents & NHIs and click Add policy tag. The tab appears only if your role can view policies.
Slack MCP server page with the prod and pii policy tags beside its tabs, and the send_message tool carrying the built-in write and external tags
Your own policy tags sit beside the server's tabs, and each tool lists its tags on its own row

Filtering by policy tag

The Resource policy tag filter on MCP Servers & Tools, and the Agent policy tag filter on the Agents tab of Agents & NHIs, show only what carries the policy tags you pick, such as every MCP server tagged prod. On MCP Servers & Tools, the filter lists only your own policy tags, not built-in ones, and finds servers, not individual tools.

Agent Trail and MCP usage analytics also filter by policy tag: an Agent policy tag chip scopes events and metrics to agents carrying it, and a Resource policy tag chip scopes to the MCP servers and tools carrying it.

Using policy tags in policies

A policy rule that matches a policy tag covers every current and future agent, server or tool that carries it: tag a new server prod and your prod rules apply immediately, with no policy edit. See the policies guide for details.

Conditions can test policy tags too: reference agent.tags, mcp.tags, or mcp.tool.tags in a CEL expression, such as "pii" in mcp.tags. See Conditions.

Example: let agents only read

An allow rule that picks the built-in tag read-only in the Tools pill lets agents read across every server, including servers you add later. Turn off the Allow all rule that SecureAuth creates by default, and everything else is denied. The rule misses tools without built-in tags, so check the limits.

Connecting by policy tag

You can connect an agent to only the MCP servers and tools that carry the Resource tags you choose. Add ?tags= to the gateway URL, or pick Policy tags in the connect dialog. See Scope a connection.

Next steps

You now know which kind of policy tag goes where, and how rules, filters, and connections use it. Next, tag the agents or servers a rule should cover, then match that policy tag in a policy.

  • Tool policy tags – how policy tags work for MCP servers and their tools.
  • Policies – use policy tags as scope pills or inside CEL conditions.
  • Agent Trail – filter the event feed by Agent or Resource policy tag.
  • MCP usage analytics – narrow every chart to a tagged slice of your org.

On this page