# Tool catalogs and permissions

Use real tool names in policies and enforce restrictions at discovery and call time.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/mcp/catalog

## Discovery is policy context

The local gateway observes `tools/list`, reports supported catalog information to Kastra, and filters tools named in the returned hidden set. Large catalogs can be truncated and descriptions shortened. Treat a partial catalog as partial evidence, not as a complete inventory.

## Hide and deny serve different moments

A hide rule can keep a tool out of discovery. Call-time policy still checks an explicit invocation, including a name an agent remembers. Hiding alone is not a security boundary; verify both paths.

Use the actual tool name, server identity, transport, and argument shape recorded by the integration. Local and hosted MCP namespaces differ. A policy written for a coding-agent hook may not match a third-party MCP call.

## Draft against connected tools

The current AI drafter can use the workspace's available MCP catalog. Review the matching-tool notes, scope warnings, and example test results before installing a draft. A name match proves neither that every possible argument is safe nor that every server is reachable.

## Verify a permission change

Refresh discovery, confirm the advertised tool list, and attempt an explicit harmless call to a restricted tool in a test environment. Inspect the matching rule and outcome. If catalog discovery fails, the gateway can return the original unfiltered list; the [failure guide](https://docs.kastra.ai/reference/failure-behavior) explains why visible tools alone are not proof of policy state.