Netlify MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:138-198 (registration)

  Registers the grouped 'netlify-extension-services-updater' tool (when operationType='write' and domain='extension') including schema (selector union) and dispatching handler logic.

    // Register tools grouped by domain with selector (uses anyOf/union)
    const paramsSchema = {
      // @ts-ignore
      selectSchema: tools.length > 1 ? z.union(tools.map(tool => toSelectorSchema(tool))) : toSelectorSchema(tools[0])
    };
  
    const friendlyOperationType = operationType === 'read' ? 'reader' : 'updater';
    const toolName = `netlify-${domain}-services-${friendlyOperationType}`;
    const toolDescription = `Select and run one of the following Netlify ${operationType} operations${readOnlyIndicator} ${toolOperations.join(', ')}`;
  
    server.registerTool(toolName, {
      description: toolDescription,
      inputSchema: paramsSchema,
      annotations: {
        readOnlyHint: operationType === 'read'
      }
    }, async (...args) => {
      checkCompatibility();
  
      try {
        await getNetlifyAccessToken(remoteMCPRequest);
      } catch (error: NetlifyUnauthError | any) {
        if (error instanceof NetlifyUnauthError && remoteMCPRequest) {
          throw new NetlifyUnauthError();
        }
  
        return {
          content: [{ type: "text", text: error?.message || 'Failed to get Netlify token' }],
          isError: true
        };
      }
  
      appendToLog(`${toolName} operation: ${JSON.stringify(args)}`);
  
      const selectedSchema = args[0]?.selectSchema as any;
  
      if (!selectedSchema) {
        return {
          content: [{ type: "text", text: 'Failed to select a valid operation. Retry the MCP operation but select the operation and provide the right inputs.' }]
        }
      }
  
      const operation = selectedSchema.operation;
  
      const subtool = tools.find(subtool => subtool.operation === operation);
  
      if (!subtool) {
        return {
          content: [{ type: "text", text: 'Agent called the wrong MCP tool for this operation.' }]
        }
      }
  
      const result = await subtool.cb(selectedSchema.params || {}, {request: remoteMCPRequest, isRemoteMCP: !!remoteMCPRequest});
  
      appendToLog(`${domain} operation result: ${JSON.stringify(result)}`);
  
      return {
        content: [{ type: "text", text: JSON.stringify(result) }]
      }
    });
  }

• src/tools/extension-tools/index.ts:2-8 (helper)

  Defines the extensionDomainTools array listing all extension tools, from which read/write are categorized and the write ones ('change-extension-installation', 'initialize-database') are grouped under the updater service.

  import { changeExtensionInstallationDomainTool } from './change-extension-installation.js';
  import { getExtensionsDomainTool } from './get-extensions.js';
  import { getFullExtensionDetailsDomainTool } from './get-full-extension-details.js';
  import { initializeDatabaseDomainTool } from './initialize-database.js';
  
  export const extensionDomainTools = [changeExtensionInstallationDomainTool, getExtensionsDomainTool, getFullExtensionDetailsDomainTool, initializeDatabaseDomainTool]

• src/tools/extension-tools/change-extension-installation.ts:14-62 (handler)

  Core handler (cb) for the 'change-extension-installation' operation dispatched by netlify-extension-services-updater; handles installing/uninstalling extensions and provides config URLs.

  export const changeExtensionInstallationDomainTool: DomainTool<typeof changeExtensionInstallationParamsSchema> = {
    domain: 'extension',
    operation: 'change-extension-installation',
    inputSchema: changeExtensionInstallationParamsSchema,
    toolAnnotations: {
      readOnlyHint: false,
    },
    cb: async ({ extensionSlug, shouldBeInstalled, teamId, siteId }, {request}) => {
  
      try {
  
        await changeExtensionInstallation({
          shouldBeInstalled,
          accountId: teamId,
          extensionSlug,
          request,
        });
  
        appendToLog(`Extension "${extensionSlug}" successfully ${shouldBeInstalled ? 'installed' : 'uninstalled'} on account "${teamId}"`);
  
        // Check if extension has site-level configuration
        const extensionData = await getExtension({
          accountId: teamId,
          extensionSlug,
          request
        });
  
        if (extensionData?.uiSurfaces?.includes('extension-team-configuration')) {
          if (shouldBeInstalled) {
            return `Extension has been installed successfully. Configure it here: https://app.netlify.com/team/${teamId}/extension/${extensionSlug}`
          }
        }else if (siteId && extensionData.uiSurfaces?.includes('extension-top-level-site-configuration')) {
          const site = await getSite({ siteId, incomingRequest: request });
  
          if(shouldBeInstalled){
            return `Extension has been installed successfully. Configure it here: https://app.netlify.com/sites/${site.name}/extensions/${extensionSlug}`
          }
        }
  
      } catch (error: any) {
        const errorMessage = error.message || 'Failed to install extension';
        appendErrorToLog(errorMessage);
        return `Failed to ${shouldBeInstalled ? 'install' : 'uninstall'} the extension. Ensure the extension slug is correct but getting the list of extensions. Error: ${errorMessage}`
      }
  
      return `Extension ${shouldBeInstalled ? 'installed' : 'uninstalled'} successfully.`;
    }
  };

• src/tools/extension-tools/initialize-database.ts:7-18 (handler)

  Handler (cb) for the 'initialize-database' operation dispatched by netlify-extension-services-updater; provides instructions for database setup.

  export const initializeDatabaseDomainTool: DomainTool<typeof initializeDatabaseParamsSchema> = {
    domain: 'extension',
    operation: 'initialize-database',
    inputSchema: initializeDatabaseParamsSchema,
    toolAnnotations: {
      readOnlyHint: false,
    },
    cb: async () => {
      return 'Ensure the @netlify/neon npm package is installed. After installation, restart the development server or run new build.';
    }
  }

• src/tools/tool-utils.ts:11-19 (helper)

  Helper function that categorizes domain tools into readOnlyTools and writeTools based on readOnlyHint annotation, enabling separate registration of reader/updater services.

  export const categorizeToolsByReadWrite = (domainTools: DomainTool<any>[]) => {
    const readOnlyTools = domainTools.filter(tool => tool.toolAnnotations.readOnlyHint === true);
    const writeTools = domainTools.filter(tool => tool.toolAnnotations.readOnlyHint === false || tool.toolAnnotations.readOnlyHint === undefined);
    
    return {
      readOnlyTools,
      writeTools
    };
  };