Tool Catalog

The tool catalog is MITRITY's registry of every tool, API, service or resource that your AI agents can interact with. Cataloging a tool gives you fine-grained governance. Instead of writing policies against raw action strings, you can:

• grant Capabilities at the tool level, with operation-level granularity;
• set rate limits;
• track usage patterns.

Browse the catalog at /app/tools. The page is split into three tabs:

• Built-in (the default): the 76-tool catalog that MITRITY ships. It is read-only for you, and MITRITY maintains it.
• Custom: the tools your tenant has authored. You create, edit and delete them here.
• All: a flat view across both sources.

Click any tool row to see its full operation list, grouped by underscore prefix (for example list_*, create_*), along with the action-type pattern, the scopes and the resource pattern.

Built-in vs custom tools

You cannot modify built-in tools. The backend rejects changes to is_builtin=true rows, so that the catalog stays consistent across tenants. To request a new built-in tool, file a request with support. Meanwhile, you can ship the same shape as a custom tool right away.

Categories

Every tool belongs to one of 13 categories. The set is fixed, and the backend rejects unknown values:

Categories are used for filtering in the dashboard, for grouping in compliance reports and for applying category-wide permissions.

What the v1 built-in catalog covers

The v1 built-in catalog ships 76 tools across all 13 categories. A representative sample:

The rows the edge can enforce

A capability on a catalog row restricts a call only when the row's pattern matches the action type an edge surface records. 16 of the 76 rows do:

A namespaced row matches only calls through a gateway that serves the upstream under exactly that namespace. If your gateway serves Stripe's MCP server under another namespace, grant a definition of your own with that namespace instead.

The other 60 rows are the 59 rows that carry a vendor's own pattern (s3:*, github:*, postgres:*, slack:*, jira:*, confluence:*, notion:*, aws-bedrock:*, azure-openai:*, vertex:*, gemini:*, python:*, webfetch:* and so on), and HTTP Client (http:*). No edge surface records those action types, so a capability on one of them would match no call and restrict nothing:

• The API refuses an enabled capability on any of the 60 rows with 422, naming [<i>].tool_id. It refuses a policy rule bound to a vendor-pattern row the same way, naming the rule's tool_definition_id.
• The Capabilities dialog does not list the 60 rows. A capability saved on one earlier still opens in the dialog, with a note, so that you can switch it off or remove it.
• To govern a vendor's tools, serve its MCP server through Mitrity Gateway, and grant a definition whose pattern names that namespace: one of the rows above, or your own mcp:<namespace>__* definition.

The operations of each built-in tool are taken verbatim from canonical sources, in this order of preference:

1. the vendor's MCP server, where one exists;
2. the official SDK's method names;
3. the REST API's endpoint inventory, as a last resort.

The names match what you would see in the vendor's docs (for example Slack's chat.postMessage, AWS S3's get_object). So a policy author can paste an operation back into the vendor's documentation to confirm what it does.

Several tools have Admin variants. The split separates routine operations (read, list, query) from dangerous ones (DDL, IAM, account and instance management), so that you can grant the broad surface widely and the admin surface narrowly. For example:

• Stripe covers customers, products, prices, invoices and refunds (create_customer, list_invoices, create_refund, …).
• Stripe Admin covers accounts, coupons, webhook endpoints and API keys (delete_account, create_api_key, …). Gate it behind a stricter capability and an approval flow.

MITRITY-platform tools

Two rows describe MITRITY-platform tools rather than a vendor's API. Like the other namespaced rows, each one matches only calls through a gateway that serves an upstream under exactly that namespace.

Both ship as built-ins, so that the multi-agent demo works without creating tools per tenant.

Authoring a custom tool

On /app/tools, open the Custom tab and click Add tool. The required fields:

• Name: the display name (for example Internal CRM).
• Category: one of the 13 above. Pick custom if none of the others fit.
• Action type pattern: a glob matched against the action type that the edge records. For tools that a gateway serves, write mcp:<namespace>__* with the namespace the gateway serves the upstream under (for example mcp:crm__*). You can save a pattern such as crm:*, but it names no surface the edge records, so it matches no call, and the API refuses an enabled capability on it, or a policy rule bound to it, with 422.
• Operations: a comma-separated list of operation names. On an mcp:<namespace>__* definition, list the upstream's tool names without the namespace (for example list_contacts, update_deal). The edge reads a call to one as crm__list_contacts (Agent Capabilities).

The optional fields:

• Resource pattern: a second glob, matched against the action's target. The tool matches when both patterns match. On a gateway call, the target is the served name (crm__list_contacts), so a resource pattern written with the tools' own names matches no call.
• Scopes: a list of named scopes that the tool exposes (for example prod, staging). You grant subsets of them per agent, through the Capabilities form's allowed_scopes / denied_scopes.

Once you save the tool, you can grant it right away, from any agent's detail page under Capabilities → Add capability.

Edit and delete

Rows your tenant owns have edit and delete actions. Editing a tool changes the operations and scopes of all its existing Capability grants automatically, because Capabilities reference the tool by ID, not by snapshot. An edit that sends match rules must name an action type pattern. While any capability on the tool is switched on, an edit cannot change the match rules to ones the edge cannot enforce: switch those capabilities off or remove them first. A tool stored without an action type pattern before these checks does not reach your edges: the calls its capabilities covered go to other capabilities or to the policy rules. Deleting cascades: any agent capabilities that reference the tool are removed too, and those agents fall back to policy-rule evaluation for the affected actions.

Match rules

Match rules determine how raw agent actions map to tool catalog entries.

Action type patterns

Action type patterns use glob syntax to match the action type that the edge records on each event:

The part before the first colon names the surface that saw the call: mcp for Mitrity Gateway, Mitrity MCP Sidecar and Mitrity Mesh Authorizer, llm for Mitrity LLM Gateway, shell for the governed shell, builtin for framework built-in tools, and egress and delegate for mesh egress and agent-to-agent hops. What an action type looks like lists each form. A pattern that starts with anything else, such as a vendor's own name (s3:*, github:*), matches no call.

The gateway serves an upstream's tools as <namespace>__<tool>, so the namespace and the tool name are joined by a double underscore, never a colon.

Resource patterns

Resource patterns match an action's target. The target depends on the surface:

Combined with an action type pattern, a resource pattern lets you scope a definition narrowly: for example, mcp:stripe__* with the resource pattern stripe__list_* matches only Stripe's list_* tools.

Operations

A tool's operations are the names that you grant in a capability. The catalog uses verbatim names from canonical sources, not a normalized read/write/delete vocabulary. For example:

• Stripe: create_customer, list_invoices, create_refund
• Sentry: search_issues, update_issue
• MCP Delegate: delegate_to
• AWS S3: get_object, put_object, list_objects_v2, delete_object (from the AWS SDK)
• GitHub: 143 operations, including dispatcher sub-resources like actions_run_trigger:cancel_workflow_run

So a policy author can paste an operation back into the vendor's docs to confirm what it does. On an mcp:<namespace>__* row, an operation is a tool's own name, and the edge reads the call as <namespace>__<tool>. Agent Capabilities explains how each surface reads operations.

Some tools have large surfaces: 49 operations for ClickUp, 21 for MongoDB. The Capabilities picker groups them by prefix. It also offers Use wildcard * as a shortcut for "grant everything this tool exposes, now and in the future".

API reference

GET /api/v1/tools and GET /api/v1/tools/{tool_id} are available to any authenticated tenant key. POST, PUT and DELETE enforce tenant ownership, and reject changes to is_builtin=true rows.

List tools

curl https://api.mitrity.com/api/v1/tools \
  -H "Authorization: Bearer mk_your-api-key"

Query parameters:

Create a custom tool

curl -X POST https://api.mitrity.com/api/v1/tools \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal CRM",
    "category": "custom",
    "match_rules": {
      "action_type_pattern": "mcp:crm__*"
    },
    "operations": ["list_contacts", "get_contact", "update_contact", "list_deals", "create_deal"],
    "scopes": ["sales", "support"]
  }'

Update or delete

PUT /api/v1/tools/{tool_id} and DELETE /api/v1/tools/{tool_id} accept tenant-owned tool IDs, and return 403 on built-ins or cross-tenant requests.

An update that sends match_rules must include an action_type_pattern that is not blank, or it gets 400. While any capability on the tool is switched on, the API refuses with 422 new match rules that the edge cannot enforce: a vendor pattern, the reserved http surface, a malformed glob, or a resource pattern that can never match. The field error is on match_rules.action_type_pattern or match_rules.resource_pattern, and it names agents that hold those capabilities. Switch the capabilities off ("enabled": false through PUT /api/v1/agents/{agent_id}/permissions) or remove them, then change the tool. Match rules sent back exactly as stored are accepted. Delete cascades into tool_permissions: existing grants for the deleted tool are removed, and those agents fall back to policy-rule evaluation for the affected actions.

Best practices

Lean on the built-in catalog

The 76 built-ins are sourced from canonical APIs and updated as vendors evolve. Granting the built-in Stripe row gets you the tool names Stripe's MCP server serves. A Stripe custom tool of your own with [send, read, list] names no tool the gateway serves, so a capability listing those operations refuses every call.

Use the Admin tier

For high-stakes tools (payments, accounts, org admin), prefer to grant the base tier widely and to gate the Admin tier behind a stricter capability and an approval flow: Stripe and Stripe Admin, Sentry and Sentry Admin. The split is deliberate: deleting an account or creating an API key should never travel with listing invoices.

Match the integration surface in the pattern

If your agent reaches a vendor's MCP server through Mitrity Gateway, match the namespace the gateway serves it under: mcp:<namespace>__*. A call that the agent makes with the vendor's SDK directly does not reach the gateway, and no edge surface records a vendor-named action type such as slack:*. Governance Coverage explains which paths MITRITY governs.

Periodic catalog review

The Built-in tab gets new tools as MITRITY adds them. The Custom tab shows what your tenant has accumulated. Review it monthly, and prune tools that no agent uses: orphan custom tools complicate capability audits.

Related documentation

• Agent Capabilities: grant per-agent tool capabilities
• Destination Allowlists: control where agents can send data
• Delegation Chains: MCP Delegate, privilege escalation, chain governance
• Approvals: MCP Approve, hold-and-release flows
• Writing Policies: policy structure and pattern matching
• API Overview: the full API reference