MCP Registry Server

Instructions

Implementation Reference

• src/tools/listMcpServers.ts:15-54 (handler)

  The core handler function that fetches MCP servers from the specified registry URL (default official), applies pagination via limit and cursor, fetches JSON data, adds pagination hints and count info, and returns formatted text content with the servers data for semantic analysis.

  async ({ limit = 50, cursor, registry_url = DEFAULT_REGISTRY_URL }) => {
      const url = new URL(registry_url);
      
      if (cursor) {
          url.searchParams.set("cursor", cursor);
      }
      
      if (limit) {
          url.searchParams.set("limit", limit.toString());
      }
  
      const response = await fetch(url.toString());
      
      if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
  
      const data = await response.json();
      
      // Return all servers without filtering - let semantic search handle matching
      const hasMoreData = data.metadata && data.metadata.next_cursor;
      const paginationHint = hasMoreData 
          ? `Note: This is a paginated result. There are more MCP servers available. Use cursor "${data.metadata.next_cursor}" to retrieve the next page.\n\n`
          : '';
      
      const totalCount = data.servers ? data.servers.length : 0;
      const countInfo = `Total MCP servers in this response: ${totalCount}\n\n`;
      
      return {
          content: [
              {
                  type: "text",
                  text: `${countInfo}${paginationHint}${JSON.stringify({
                      servers: data.servers,
                      metadata: data.metadata
                  }, null, 2)}`
              }
          ]
      };
  }

• src/tools/listMcpServers.ts:10-14 (schema)

  Zod schema defining the input parameters for the list_mcp_servers tool: optional limit (1-100), cursor for pagination, and optional registry_url.

  {
      limit: z.number().min(1).max(100).optional().describe("Maximum number of servers to return (1-100, default: 50)"),
      cursor: z.string().optional().describe("Pagination cursor for retrieving next set of results"),
      registry_url: z.string().url().optional().describe("Base URL of the MCP Registry API (defaults to official registry - https://registry.modelcontextprotocol.io/v0/servers)")
  },

• src/tools/listMcpServers.ts:6-56 (registration)

  The registration function that adds the 'list_mcp_servers' tool to the MCP server instance, specifying name, description, input schema, and handler.

  export function registerListMcpServers(server: McpServer) {
      server.tool(
          "list_mcp_servers",
          "List MCP servers from the MCP Registry with optional pagination. Returns raw server data for semantic analysis.",
          {
              limit: z.number().min(1).max(100).optional().describe("Maximum number of servers to return (1-100, default: 50)"),
              cursor: z.string().optional().describe("Pagination cursor for retrieving next set of results"),
              registry_url: z.string().url().optional().describe("Base URL of the MCP Registry API (defaults to official registry - https://registry.modelcontextprotocol.io/v0/servers)")
          },
          async ({ limit = 50, cursor, registry_url = DEFAULT_REGISTRY_URL }) => {
              const url = new URL(registry_url);
              
              if (cursor) {
                  url.searchParams.set("cursor", cursor);
              }
              
              if (limit) {
                  url.searchParams.set("limit", limit.toString());
              }
  
              const response = await fetch(url.toString());
              
              if (!response.ok) {
                  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
              }
  
              const data = await response.json();
              
              // Return all servers without filtering - let semantic search handle matching
              const hasMoreData = data.metadata && data.metadata.next_cursor;
              const paginationHint = hasMoreData 
                  ? `Note: This is a paginated result. There are more MCP servers available. Use cursor "${data.metadata.next_cursor}" to retrieve the next page.\n\n`
                  : '';
              
              const totalCount = data.servers ? data.servers.length : 0;
              const countInfo = `Total MCP servers in this response: ${totalCount}\n\n`;
              
              return {
                  content: [
                      {
                          type: "text",
                          text: `${countInfo}${paginationHint}${JSON.stringify({
                              servers: data.servers,
                              metadata: data.metadata
                          }, null, 2)}`
                      }
                  ]
              };
          }
      );
  }

• src/server.ts:2-10 (registration)

  Imports and calls registerListMcpServers during server creation to register the tool with the MCP server.

  import { registerListMcpServers } from "./tools/listMcpServers.js";
  
  export function createServer(): McpServer {
    const server = new McpServer({
      name: "MCP Server for MCP Registry",
      version: "0.1.0",
    });
  
    registerListMcpServers(server);

• src/tools/listMcpServers.ts:4-5 (helper)

  Default URL for the official MCP Registry API used in the tool handler.

  const DEFAULT_REGISTRY_URL = "https://registry.modelcontextprotocol.io/v0/servers";