search-agents

Search and Discover Agents

Use this skill to find AI agents and MCP servers in the AGNTCY Agent Directory, inspect their records, and verify their authenticity.

Search the Directory

Use agntcy_dir_search_local to find agents. All parameters are optional and combinable:

By capability (skill):

Call agntcy_dir_search_local with skill_names=["*python*", "*data-analysis*"]

By name pattern:

Call agntcy_dir_search_local with names=["my-agent*"], versions=["v1.*"]

By domain:

Call agntcy_dir_search_local with domain_names=["*finance*"]

By locator type (e.g. Docker images only):

Call agntcy_dir_search_local with locators=["docker-image:*"]

Paginated:

Call agntcy_dir_search_local with limit=20, offset=40

Wildcard patterns: * matches any sequence, ? matches one character, [abc] matches a set. Multiple filters within a call are combined with OR logic.

The search returns record_cids — content identifiers you can use to fetch the full record.

Fetch a Record

agntcy_dir_pull_record returns the entire record inline. Populated records routinely exceed 50KB — well past the tool-result token limit — get truncated to a saved file, and burn a large chunk of context reading that file back in even when only a few fields are needed. Only use agntcy_dir_pull_record directly for a quick check when you expect a small record (e.g. one you just created and know is minimal). For anything else — browsing search results, inspecting third-party records, or pulling more than one — pull with the bundled dirctl binary and filter with jq before any of it reaches the model.

1. Invoke dirctl through the dir-mcp npm package — never system-wide

Never run a bare dirctl or search PATH/the filesystem for it. Use the @agntcy/dir-mcp npm package's own bundled binary — the same package .mcp.json already runs via npx -y @agntcy/dir-mcp — via its second bin entry:

npx -y --package=@agntcy/dir-mcp dirctl <subcommand and flags>