Search Registry

Search Registry Skill

Search the MCP Gateway Registry for MCP servers, tools, A2A agents, skills, and virtual servers using the ai-registry-tools MCP server.

Prerequisites

The user must have the AI Registry MCP server connected to their AI Assistant session. It may be registered under various names including:

• ai-registry-tools
• airegistry-tools
• ai_registry_tools
• registry-tools
• mcp-registry

The key indicator is that one of these tools should be available:

• mcp__ai-registry-tools__search_registry
• mcp__airegistry-tools__search_registry
• or similar variations

Input

The skill accepts a natural language search query:

/search-registry <query>

• query - What capability, tool, server, or agent the user is looking for (natural language)

If no query is provided, ask the user: "What would you like to search for in the registry?"

Examples

/search-registry tools for weather data
/search-registry exchange rates currency conversion
/search-registry document processing PDF
/search-registry travel booking flights

Workflow

Step 1: Find the Registry Search Tool

Look for the search_registry tool from the ai-registry-tools MCP server. It may be available under different prefixes depending on how the user registered the server. Try these in order:

1. mcp__ai-registry-tools__search_registry
2. mcp__airegistry-tools__search_registry
3. mcp__ai_registry_tools__search_registry
4. mcp__registry-tools__search_registry
5. mcp__mcp-registry__search_registry

Use ToolSearch to find the correct tool name if none of the above work. Search for "search_registry" or "registry search".

If the tool cannot be found, tell the user:

"The AI Registry MCP server is not connected to this AI Assistant session. You need to add it first. See the registry documentation for connection instructions specific to your AI Assistant (Claude Code, Codex CLI, etc.)."

Step 2: Execute the Search

Call the search_registry tool with:

• query: the user's natural language query
• max_results: 10

Step 3: Present Results

Display the results in this format:

### Registry Search Results

**Query:** {query}
**Found:** {count} servers, {count} tools, {count} agents, {count} skills

---

For each result category that has results, show a table:

MCP Servers

For servers with matching_tools, list them below:

{server_name} matching tools:

Tools

A2A Agents

Skills

After the tables, provide a brief plain-text summary of the top 3-5 most relevant results.

Step 4: Offer to Add MCP Servers

IMPORTANT: After presenting results, if any MCP servers were found that have an endpoint_url, ask the user:

"Would you like to add any of these MCP servers to your AI Assistant configuration? If so, which one(s)?"

Present the available servers as options (only those with a valid endpoint_url).

Step 5: Add Server to AI Assistant

If the user says yes and picks a server, determine which AI Assistant is being used and add the server using the appropriate method for that assistant.

Detecting the AI Assistant

Check for configuration files to determine the assistant in use:

1. Claude Code: Look for .mcp.json in the project root or ~/.claude/settings.json
2. Codex CLI: Look for codex.json or .codex/ configuration directory
3. Other assistants: Ask the user which assistant they are using if it cannot be determined automatically

Adding for Claude Code

Method 1 (preferred): Use the claude mcp add command

Run this command (either in a terminal or prefixed with ! inside a Claude Code session):

claude mcp add --transport http --scope user <server-name> <endpoint_url>

For example:

claude mcp add --transport http --scope user real-server-fake-tools https://mcpgateway.ddns.net/realserverfaketools/mcp

This saves the server to ~/.claude.json at user scope, making it available across all projects.

Method 2: Update ~/.claude.json directly

Add the new server to the mcpServers object in ~/.claude.json (the user-level config file where ai-registry-tools and other MCP Gateway servers are configured):

{
  "mcpServers": {
    "existing-server": { ... },
    "new-server-name": {
      "type": "http",
      "url": "<endpoint_url from the search result>"
    }
  }
}

Note: Do NOT add servers to the project-level .mcp.json file. That file is committed to git and should not contain user-specific MCP server configurations. Use ~/.claude.json (user scope) for servers that persist across projects.

Adding for Codex CLI

Update the Codex MCP configuration file (typically ~/.codex/mcp.json or the project-level equivalent):

{
  "servers": {
    "new-server-name": {
      "url": "<endpoint_url from the search result>"
    }
  }
}

Or use the Codex CLI command if available:

codex mcp add <server-name> --url <endpoint_url>

Adding for Other Assistants

If the AI Assistant cannot be determined or is not one of the above, provide the user with the raw connection details and let them configure it manually:

"Here are the connection details for the server:

• Name: {server_name}
• Endpoint URL: {endpoint_url}
• Transport: streamable-http

Add this to your AI Assistant's MCP server configuration using the method appropriate for your tool."