inkog_audit_mcp_server

Audit MCP servers for security risks by analyzing tool permissions, data flow vulnerabilities, and input validation before installation.

Instructions

Security audit any MCP server from the registry or GitHub. Analyzes tool permissions, data flow risks, input validation, and potential vulnerabilities. Use this before installing any new MCP server to verify it is safe.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`server_name`	No	MCP server name from registry (e.g., "github", "slack", "postgres")
`repository_url`	No	Direct GitHub repository URL to audit

Implementation Reference

src/tools/audit-mcp.ts:87-317 (handler)

The 'auditMcpHandler' function implements the logic for 'inkog_audit_mcp_server', handling argument validation, API calls to the Inkog security platform, and formatting the security report for the user.

async function auditMcpHandler(rawArgs: Record<string, unknown>): Promise<ToolResult> {
  // Validate arguments
  const parseResult = AuditMcpArgsSchema.safeParse(rawArgs);
  if (!parseResult.success) {
    return {
      content: [
        {
          type: 'text',
          text: `Invalid arguments: ${parseResult.error.message}\n\nProvide either server_name (from MCP registry) or repository_url (GitHub URL).`,
        },
      ],
      isError: true,
    };
  }

  const args: AuditMcpArgs = parseResult.data;

  try {
    // Call Inkog API
    const client = getClient();
    const auditOptions: { serverName?: string; repositoryUrl?: string } = {};
    if (args.server_name !== undefined) {
      auditOptions.serverName = args.server_name;
    }
    if (args.repository_url !== undefined) {
      auditOptions.repositoryUrl = args.repository_url;
    }
    const response = await client.auditMcpServer(auditOptions);

    // Build formatted output
    let output = '╔══════════════════════════════════════════════════════╗\n';
    output += '║           🔒 MCP Server Security Audit                ║\n';
    output += '╚══════════════════════════════════════════════════════╝\n\n';

    // Show cache warning if using offline data
    if (response.cache_warning) {
      output += `⚠️  ${response.cache_warning}\n\n`;
    }

    // Get data using new field names (with fallbacks for legacy compatibility)
    const serverInfo = response.server ?? response.serverInfo;
    const auditResults = response.audit_results;
    const findings = response.findings ?? response.issues ?? [];
    const securityScore = auditResults?.security_score ?? response.securityScore ?? 0;

    // Server info
    if (serverInfo) {
      output += `📦 Server: ${serverInfo.name}\n`;
      if (serverInfo.description) {
        output += `   ${serverInfo.description}\n`;
      }
      if (serverInfo.repository) {
        output += `🔗 Repository: ${serverInfo.repository}\n`;
      }
      if (serverInfo.license) {
        output += `📄 License: ${serverInfo.license}\n`;
      }
      output += '\n';
    }

    // Security score
    output += `📊 Security Score: ${formatSecurityScore(securityScore)}\n`;
    if (auditResults?.overall_risk) {
      output += `📈 Overall Risk: ${auditResults.overall_risk.toUpperCase()}\n`;
    }
    output += '\n';

    // Findings summary
    const critical = findings.filter((i) => i.severity === 'CRITICAL' || i.severity === 'critical').length;
    const high = findings.filter((i) => i.severity === 'HIGH' || i.severity === 'high').length;
    const medium = findings.filter((i) => i.severity === 'MEDIUM' || i.severity === 'medium').length;
    const low = findings.filter((i) => i.severity === 'LOW' || i.severity === 'low').length;

    if (findings.length === 0) {
      output += '✅ No security issues detected!\n\n';
    } else {
      output += `📋 Security Issues: ${findings.length}\n`;
      output += `   🔴 Critical: ${critical} | 🟠 High: ${high} | 🟡 Medium: ${medium} | 🟢 Low: ${low}\n\n`;
    }

    // Permissions analysis
    if (response.permissions) {
      const perms = response.permissions;
      output += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n';
      output += '🔐 PERMISSIONS ANALYSIS\n\n';
      output += `   Scope: ${perms.scope}\n`;
      if (perms.file_access) output += '   📁 File System Access\n';
      if (perms.network_access) output += '   🌐 Network Access\n';
      if (perms.code_execution) output += '   ⚡ Code Execution\n';
      if (perms.database_access) output += '   🗄️  Database Access\n';
      if (perms.environment_access) output += '   🔧 Environment Access\n';
      output += '\n';
    }

    // Tools analysis
    if (response.tools && response.tools.length > 0) {
      output += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n';
      output += '🔧 TOOLS ANALYSIS\n\n';
      for (const tool of response.tools) {
        const riskIcon = tool.risk_level === 'dangerous' ? '🔴' : tool.risk_level === 'moderate' ? '🟡' : '🟢';
        output += `   ${riskIcon} ${tool.name} (${tool.risk_level})\n`;
        if (tool.risk_reasons && tool.risk_reasons.length > 0) {
          for (const reason of tool.risk_reasons) {
            output += `      • ${reason}\n`;
          }
        }
      }
      output += '\n';
    }

    // Detailed findings
    if (findings.length > 0) {
      output += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n';
      output += '🔍 SECURITY FINDINGS\n\n';

      // Critical and high first
      const criticalHigh = findings.filter(
        (i) => i.severity === 'CRITICAL' || i.severity === 'critical' ||
               i.severity === 'HIGH' || i.severity === 'high'
      );
      const mediumLow = findings.filter(
        (i) => i.severity === 'MEDIUM' || i.severity === 'medium' ||
               i.severity === 'LOW' || i.severity === 'low'
      );

      for (const finding of criticalHigh) {
        output += `${formatSeverityIcon(finding.severity.toUpperCase() as Severity)} [${finding.severity.toUpperCase()}] ${finding.title}\n`;
        output += `   ${finding.description}\n`;
        if (finding.remediation) {
          output += `   💡 ${finding.remediation}\n`;
        }
        output += '\n';
      }

      if (mediumLow.length > 0 && criticalHigh.length > 0) {
        output += '--- Lower Severity ---\n\n';
      }

      for (const finding of mediumLow) {
        output += `${formatSeverityIcon(finding.severity.toUpperCase() as Severity)} [${finding.severity.toUpperCase()}] ${finding.title}\n`;
        output += `   ${finding.description}\n`;
        if (finding.remediation) {
          output += `   💡 ${finding.remediation}\n`;
        }
        output += '\n';
      }
    }

    // Recommendations
    if (response.recommendations.length > 0) {
      output += '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n';
      output += '💡 RECOMMENDATIONS\n\n';
      for (let i = 0; i < response.recommendations.length; i++) {
        output += `${i + 1}. ${response.recommendations[i]}\n`;
      }
    }

    // Footer
    output += '\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n';
    output += 'MCP Server Audit powered by Inkog AI Security Platform\n';
    output += 'Learn more: https://inkog.io/mcp-security\n';

    return {
      content: [
        {
          type: 'text',
          text: output,
        },
      ],
    };
  } catch (error) {
    if (error instanceof InkogAuthError) {
      return {
        content: [
          {
            type: 'text',
            text: '🔐 API Key Required\n\nGet your free key at https://app.inkog.io',
          },
        ],
        isError: true,
      };
    }

    if (error instanceof InkogRateLimitError) {
      return {
        content: [
          {
            type: 'text',
            text: `⏱️ Rate Limited\n\nToo many requests. Please retry after ${error.retryAfter} seconds.`,
          },
        ],
        isError: true,
      };
    }

    if (error instanceof InkogNetworkError) {
      return {
        content: [
          {
            type: 'text',
            text: `Network error: ${error.message}`,
          },
        ],
        isError: true,
      };
    }

    if (error instanceof InkogApiError) {
      return {
        content: [
          {
            type: 'text',
            text: `API error: ${error.message}${error.details ? `\n\nDetails: ${JSON.stringify(error.details)}` : ''}`,
          },
        ],
        isError: true,
      };
    }

    const message = error instanceof Error ? error.message : 'Unknown error occurred';
    return {
      content: [
        {
          type: 'text',
          text: `Error: ${message}`,
        },
      ],
      isError: true,
    };
  }
}

src/tools/audit-mcp.ts:31-45 (schema)

The 'AuditMcpArgsSchema' defines the required input parameters for the 'inkog_audit_mcp_server' tool, ensuring either a server_name or repository_url is provided.

const AuditMcpArgsSchema = z
  .object({
    server_name: z
      .string()
      .optional()
      .describe('MCP server name from registry (e.g., "github", "slack", "postgres")'),
    repository_url: z
      .string()
      .url()
      .optional()
      .describe('Direct GitHub repository URL to audit'),
  })
  .refine((data) => data.server_name !== undefined || data.repository_url !== undefined, {
    message: 'Either server_name or repository_url must be provided',
  });

src/tools/audit-mcp.ts:323-343 (registration)

The 'auditMcpTool' object exports the tool definition for 'inkog_audit_mcp_server', including its metadata, JSON schema, and the assigned handler function.

export const auditMcpTool: ToolDefinition = {
  tool: {
    name: 'inkog_audit_mcp_server',
    description:
      'Security audit any MCP server from the registry or GitHub. Analyzes tool permissions, data flow risks, input validation, and potential vulnerabilities. Use this before installing any new MCP server to verify it is safe.',
    inputSchema: {
      type: 'object',
      properties: {
        server_name: {
          type: 'string',
          description: 'MCP server name from registry (e.g., "github", "slack", "postgres")',
        },
        repository_url: {
          type: 'string',
          description: 'Direct GitHub repository URL to audit',
        },
      },
    },
  },
  handler: auditMcpHandler,
};

inkog